SIP J. Urpalainen
Internet-Draft Nokia
Intended status: Standards Track December 18, 2007
Expires: June 20, 2008
An Extensible Markup Language (XML) Configuration Access Protocol (XCAP)
Diff Event Package
draft-ietf-sip-xcapevent-00
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 June 20, 2008.
Copyright Notice
Copyright (C) The IETF Trust (2007).
Abstract
This document describes an "xcap-diff" SIP event package, with the
aid of which clients can receive notifications of the partial changes
of Extensible Markup Language (XML) Configuration Access Protocol
(XCAP) resources. The initial synchronization and document updates
are based on using the XCAP-Diff format.
Urpalainen Expires June 20, 2008 [Page 1]
Internet-Draft xcap diff event December 2007
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. XCAP-Diff Event Package . . . . . . . . . . . . . . . . . . . 4
4.1. XCAP-Diff Processing Model . . . . . . . . . . . . . . . . 4
4.2. Event Package Name . . . . . . . . . . . . . . . . . . . . 5
4.3. 'diff-processing' Event Package Parameter . . . . . . . . 5
4.4. SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . 5
4.5. Subscription Duration . . . . . . . . . . . . . . . . . . 6
4.6. NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . 6
4.7. Notifier Generation of NOTIFY Requests . . . . . . . . . . 6
4.8. Subscriber Processing of NOTIFY Requests . . . . . . . . . 8
4.9. Handling of Forked Requests . . . . . . . . . . . . . . . 8
4.10. Rate of Notifications . . . . . . . . . . . . . . . . . . 8
4.11. State Agents . . . . . . . . . . . . . . . . . . . . . . . 9
5. An Initial Example NOTIFY document . . . . . . . . . . . . . . 9
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
6.1. Registration of the "xcap-diff" Event Package . . . . . . 11
7. Security Considerations . . . . . . . . . . . . . . . . . . . 11
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11
9.1. Normative References . . . . . . . . . . . . . . . . . . . 11
9.2. Informative References . . . . . . . . . . . . . . . . . . 12
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13
Intellectual Property and Copyright Statements . . . . . . . . . . 14
Urpalainen Expires June 20, 2008 [Page 2]
Internet-Draft xcap diff event December 2007
1. Introduction
The SIP Events framework [RFC3265] describes subscription and
notification conventions for the SIP [RFC3261] protocol. The
Extensible Markup Language (XML) [W3C.REC-xml-20060816] Configuration
Access Protocol (XCAP) [RFC4825] allows a client to read, write and
modify XML formatted application usage data on an XCAP server.
While the XCAP protocol allows several authorized users or devices to
modify the same XML document, XCAP does not provide an effective
synchronization mechanism (except polling) to keep resources
equivalent between a server and a client. This memo defines an
"xcap-diff" event package that, together with the SIP event
notification framework [RFC3265] and the XCAP-diff format
[I-D.ietf-simple-xcap-diff], allows a user to subscribe to changes in
an XML document, and to receive notifications whenever a change in an
XML document takes place. It is also possible to subscribe to
documents within some collection [RFC4918], the notifier provides
then the documents where the user has read privilege.
Before being able to apply any patches into documents, a client needs
to first retrieve initial reference documents. With XCAP, this is
done with the HTTP [RFC2616] protocol. The first "xcap-diff"
notification thus contains references to subscribed documents,
thereafter notifications can contain patches to these documents.
Some clients might need to retrieve only some specific element or
attribute content from these XCAP documents without using the HTTP
protocol. All of these use-cases can be indicated with the XCAP-Diff
[I-D.ietf-simple-xcap-diff] format.
2. Terminology
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, BCP 14
[RFC2119] and indicate requirement levels for compliant
implementations.
3. Definitions
The following terms are used in this document:
Urpalainen Expires June 20, 2008 [Page 3]
Internet-Draft xcap diff event December 2007
XCAP Component: An XML element or an attribute, which can be updated
or retrieved with the XCAP protocol.
Aggregating: While XCAP clients update only a single XCAP component
at a time, several of these modifications can be aggregated
together with the XML-Patch-Ops semantics.
4. XCAP-Diff Event Package
4.1. XCAP-Diff Processing Model
When a client starts an "xcap-diff" subscription it may not be aware
of all the individual XCAP documents it is subscribing to. This can,
for instance happen when a user subscribes to his/her collection of a
given XCAP Application Usage where several different clients update
the same XCAP documents. The initial notification can give the list
of these documents which the authenticated user is allowed to read.
The references and the strong ETag values of these documents are
shown so that a client can separately fetch the actual document
contents with the HTTP protocol. After these document retrievals,
the subsequent SIP notifications can contain patches to these
documents by using XML-Patch-Ops [I-D.ietf-simple-xml-patch-ops]
semantics.
While the initial document synchronization is based on separate HTTP
retrievals of full documents, XML elements or attributes can be
received "in-band", that is straight within the <xcap-diff>
notification format. For example, an XCAP element content can be
requested without the need of a separate HTTP GET request by
providing a request URI with an XCAP Element Node Selector within the
subscription body. If the requested node can not be found with the
aid of this XCAP Node Selector value, the node content isn't
naturally shown in the notification. Once these nodes will be
created, the notification bodies will indicate their content. And
similarly, the removals of subscribed XCAP components will be
reported, for example after a successful HTTP DELETE request.
In yet another usage scenario, a subscriber to the "xcap-diff" event
might not need XML-Patch-Ops conventions at all. Indeed, the
subscriber just wants to be informed that an update has happened, but
the subscriber is not interested in learning the actual changes of
the document(s). The XCAP-Diff [I-D.ietf-simple-xcap-diff] format
will then only indicate document creations, updates and removals.
Urpalainen Expires June 20, 2008 [Page 4]
Internet-Draft xcap diff event December 2007
4.2. Event Package Name
The name of this event package is "xcap-diff". This package name is
carried in the Event and Allow-Events header, as defined in RFC3265
[RFC3265].
4.3. 'diff-processing' Event Package Parameter
The optional "diff-processing" event header parameter directs the
notifier how to apply the "XML diffing process". The possible values
are "no-patching", "xcap-patching", "aggregate". The "no-patching"
value means that only document or XCAP component existences MUST be
indicated. The "xcap-patching" value means that all individual XCAP
component updates along with the entity tag (ETag) changes MUST be
indicated. The "aggregate" value means that the notifier is free to
aggregate several individual XCAP component updates into a single
XCAP-Diff <document> element. If the subscription does not contain
this additional "diff-processing" parameter, the notifier MUST send
all individual changes so that the client receives the full ETag
change history of a document. In other words, "xcap-patching" is the
default mode.
The formal grammar [RFC4234] of the "diff-processing" parameter:
diff-processing = "diff-processing" EQUALS
"aggregate" / "no-patching" /
"xcap-patching" / token
4.4. SUBSCRIBE Bodies
When generating a subscribe request, the subscriber needs to define
the resources it is interested in getting information. This can be
done simply by sending a URI list to the SIP notifier. This list is
described with the XCAP resource list [RFC4826] document format.
Only a simple subset of that format is needed here, that is a flat
list of XCAP R-URIs. The usage of hierarchical lists and <entry>
references, etc. can thus be omitted. However, using this format
allows adding some future semantics to these subscriptions. As it is
anticipated that the XCAP server will be collocated with the SIP
notifier, the subscriber MAY use relative XCAP URIs. Although the
node-selector of XCAP allows requesting all in-scope namespaces of an
element, it is disallowed to subscribe to them with this event
package.
Urpalainen Expires June 20, 2008 [Page 5]
Internet-Draft xcap diff event December 2007
Figure 1 shows an example to a subscription of several XCAP
resources: a "resource-list" document, a specific element in a "rls-
services" document and a collection in "pidf-manipulation"
Application Usage. For all of these resources the client MUST have
read privilege in order to actually receive them in a NOTIFY request.
The "Content-Type" header of this SUBSCRIBE request is "application/
resource-lists+xml".
<?xml version="1.0" encoding="UTF-8"?>
<resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists">
<list>
<entry uri="resource-lists/users/sip:joe@example.com/index"/>
<entry uri="rls-services/users/sip:joe@example.com/index/
~~/*/service%5b@uri='sip:marketing@example.com'%5d"/>
<entry uri="pidf-manipulation/"/>
</list>
</resource-lists>
Figure 1: Example subscription body
When collections are selected as "pidf-manipulation" in the example,
the conventions applied follow the WebDAV [RFC4918] semantics, that
is, the subscriber MUST add the forward slash "/" character to the
end of the path segment. If a subscribed collection contains sub-
collections, the notifications will contain also the sub-collection
documents for which the user has read privilege.
4.5. Subscription Duration
The default expiration time for subscriptions within this package is
3600 seconds. As per RFC 3265 [RFC3265], the subscriber MAY specify
an alternative expiration timer in the Expires header field.
4.6. NOTIFY Bodies
The NOTIFY bodies will follow the conventions of the XCAP-Diff format
[I-D.ietf-simple-xcap-diff] which can indicate the full element and
attribute content of XML documents, and for documents the
corresponding URIs, the ETag values and patching instructions from
version "a" to "b". Also the removals of documents, elements and
attributes can be shown.
4.7. Notifier Generation of NOTIFY Requests
During the initial subscription the notifier MUST first resolve the
requested XCAP resources. Once there are superfluous resource
Urpalainen Expires June 20, 2008 [Page 6]
Internet-Draft xcap diff event December 2007
selections in the requested URI list, the notifier SHOULD NOT provide
overlapping similar responses for these resources. Only the
resources where the authenticated user has read privilege, will be
included in the XCAP-Diff format. Note that for example, an XCAP
component which could not be located with XCAP semantics, does not
produce an error. Instead, the request remains in a "pending" state,
that is, waiting for this resource to be created. Subscriptions to
collections have a similar property: once a new document is created
into the subscribed collection, the creation of a new resource is
notified with the next NOTIFY request. After the authorized XCAP
resources are known, the notifier will generate the first full
response with the list of authorized resources. At this time
depending on the "diff-processing" parameter, the notifier typically
starts also the follow-up of XCAP component updates and unless
otherwise directed, it reports all individual XCAP component updates
with the ETag changes to the subscriber. If the notifier process
receives then a re-subscription with the diff-processing=aggregate
value it MUST re-send the current full XML-Diff content unless the
whole request or body will be suppressed with the SubNot-Etags
[I-D.ietf-sip-subnot-etags] semantics by using the header Suppress-
If-Match: [ETag value]. The notifier SHOULD then start to aggregate
different individual patches together. The notifiers MAY decide the
appropriate aggregation semantics themselves, for example how long to
wait for subsequent patches if there's already something to signal.
It can happen in some corner cases that the notifier can not or will
not provide patches with the XML-Patch-Ops
[I-D.ietf-simple-xml-patch-ops] semantics. One example of this is
when the diff format produces a larger content than the original
document is. When this happens, and if the server has been in this
diff "aggregation" mode, it MUST fall back to the "xcap-patching"
mode for this particular resource.
It is RECOMMENDED to implement the XML-Patch-Ops processing on a
server. However, the notifier MUST support XCAP component
subscriptions. If for example, the subscriber has selected too many
elements to subscribe, so that the notification body would become
impractically large, the notifier MAY discard the <element> element
content. The existence of elements is then indicated with an empty
<element> element but the content is not shown for those resources.
Event packages like this require in practice a reliable transfer of
events. This means that all events MUST be successfully transferred
as otherwise patching will most likely fail or at least the document
content becomes to be different. RFC 3265 [RFC3265] proposes
utilization of a "version" attribute information to state deltas in
chapter 4.4. Partial-PIDF-Notify [I-D.ietf-simple-partial-notify]
requires that notifiers will not send a new request to the same
Urpalainen Expires June 20, 2008 [Page 7]
Internet-Draft xcap diff event December 2007
dialog unless a successful response (200 OK) has been received for
the last request. The latter applies also to this "xcap-diff" event
package. If the NOTIFY request fails due to a timeout condition, the
notifier MUST remove the subscription.
4.8. Subscriber Processing of NOTIFY Requests
The first NOTIFY request will typically contain references to HTTP
resources including their strong ETag values. If the subscriber does
not have similar locally cached versions, it will start an
unconditional HTTP GET request for those resources. During this HTTP
retrieval time the subscriber MAY also receive patches to these
documents (notifications) if the documents are changing frequently.
It can thus happen that the subscriber receives newer versions (with
HTTP) than what was indicated in the initial notification. However,
once all atomic XCAP modifications are indicated with both previous
and new ETags of each resource, it is easy to chain the modification
list for a document and possibly omit some of the patches based on
the received ETag (with HTTP) of a document. After that the
subscriber MAY send a re-subscription to start the diff "aggregation"
on the server.
The subscriber can use CSeq values to keep track of possible missing
NOTIFY requests. These values can easily be used to detect missing
"xcap-diff" events if there are no multiple usages in the current
dialog. Also failing patches or inconsistent ETag value changes can
be due to missing events. Once a client detects an error it MUST
renew the subscription.
If a diff format can not be applied because of some patch processing
and/or programming errors, look Section 5.1 of
[I-D.ietf-simple-xml-patch-ops], the subscriber SHOULD renew the
subscription and disable the usage of "diff-processing". It is
hardly reasonable to signal this error to the notifier even if the
error exists in the notifier process.
4.9. Handling of Forked Requests
This specification only allows a single dialog to be constructed as a
result of emitting an initial SUBSCRIBE request. In case a SUBSCRIBE
request is forked and the subscriber receives forked responses, the
subscriber MUST apply the procedures indicated in Section 4.4.9 of
RFC 3265 [RFC3265] for handling non-allowed forked requests.
4.10. Rate of Notifications
Notifiers of "xcap-diff" event package SHOULD NOT generate
notifications for a single user at a rate of more than once every
Urpalainen Expires June 20, 2008 [Page 8]
Internet-Draft xcap diff event December 2007
five seconds.
4.11. State Agents
State agents play no role in this package.
5. An Initial Example NOTIFY document
Figure 2 shows an example initial XCAP-Diff document provided by the
first NOTIFY request. The subscriber used the list as in the example
in Figure 1. An example event header of this SUBSCRIBE request:
Event: xcap-diff; diff-processing=aggregate
The subscriber requests the notifier to actually "aggregate" XCAP
component updates together. It is anticipated that the subsequent
notifications would contain aggregated patches to these documents.
Note: If these documents are changing frequently during the
initial synchronization stage, it can happen that the subscriber
can not synchronize the contents of all documents properly.
However, the subscriber can always begin with the default "xcap-
patching" mode where all individual changes with the full ETag
change history are shown and this issue does not occur.
Urpalainen Expires June 20, 2008 [Page 9]
Internet-Draft xcap diff event December 2007
<?xml version="1.0" encoding="UTF-8"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/root/">
<document new-etag="7ahggs"
sel="resource-lists/users/sip:joe@example.com/index"/>
<document new-etag="30376adf"
sel="pidf-manipulation/users/sip:joe@example.com/index"/>
<d:element sel="rls-services/users/sip:joe@example.com/index/
~~/*/service%5b@uri='sip:marketing@example.com'%5d"
xmlns:d="urn:ietf:params:xml:ns:xcap-diff"
xmlns="urn:ietf:params:xml:ns:rls-services"
xmlns:rl="urn:ietf:params:xml:ns:resource-lists"
><service uri="sip:marketing@example.com">
<list name="marketing">
<rl:entry uri="sip:joe@example.com"/>
<rl:entry uri="sip:sudhir@example.com"/>
</list>
<packages>
<package>presence</package>
</packages>
</service></d:element>
</xcap-diff>
Figure 2: An example initial XCAP-Diff document
Note that the resource-list "index" document included only the new
ETag value, as the document existed during the subscription time
(resource was not created, it just exists by the subscription time).
In the "pidf-manipulation" collection there was only a single
document where the user had read privilege. The <services> element
existed within the rls-services "index" document and its content was
shown.
6. IANA Considerations
This memo calls for IANA to:
o register a new package name per [RFC3265].
Urpalainen Expires June 20, 2008 [Page 10]
Internet-Draft xcap diff event December 2007
6.1. Registration of the "xcap-diff" Event Package
This specification instructs IANA to register an event package in the
SIP Event Types Namespace, based on the registration procedures
defined in RFC 3265 [RFC3265]. The following is the information
required for such a registration:
Package Name: xcap-diff
Package or Template-Package: This is a package.
Published Document: RFCXXXX[[NOTE TO IANA/RFC-EDITOR: Please replace
XXXX with the RFC number of this specification.]]
Person to Contact: Jari Urpalainen, jari.urpalainen@nokia.com
7. Security Considerations
This document defines a new SIP event package for the SIP event
notification framework specified in RFC 3265 [RFC3265]. As such, all
the security considerations of RFC 3265 apply. The configuration
data can contain sensitive information, and both the client and the
server need to authenticate each other. XCAP [RFC4825] provides
basic authorization policy for resources and as the notifications
will contain similar fragment content of XCAP resources the security
considerations of XCAP also apply.
8. Acknowledgments
The author would like to thank Jonathan Rosenberg for his valuable
comments and providing the initial event package, and Miguel Garcia,
Pavel Dostal, Krisztian Kiss, Anders Lindgren, Sofie Lassborn and
Keith Drage for their valuable comments.
9. References
9.1. Normative References
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston,
A., Peterson, J., Sparks, R., Handley, M., and E.
Schooler, "SIP: Session Initiation Protocol", RFC 3261,
Urpalainen Expires June 20, 2008 [Page 11]
Internet-Draft xcap diff event December 2007
June 2002.
[RFC3265] Roach, A., "Session Initiation Protocol (SIP)-Specific
Event Notification", RFC 3265, June 2002.
[RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 4234, October 2005.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC4825] Rosenberg, J., "The Extensible Markup Language (XML)
Configuration Access Protocol (XCAP)", RFC 4825, May 2007.
[RFC4826] Rosenberg, J., "Extensible Markup Language (XML) Formats
for Representing Resource Lists", RFC 4826, May 2007.
[I-D.ietf-simple-xcap-diff]
Rosenberg, J. and J. Urpalainen, "An Extensible Markup
Language (XML) Document Format for Indicating A Change in
XML Configuration Access Protocol (XCAP) Resources",
draft-ietf-simple-xcap-diff-07 (work in progress),
November 2007.
[I-D.ietf-simple-xml-patch-ops]
Urpalainen, J., "An Extensible Markup Language (XML) Patch
Operations Framework Utilizing XML Path Language (XPath)
Selectors", draft-ietf-simple-xml-patch-ops-04 (work in
progress), November 2007.
[I-D.ietf-sip-subnot-etags]
Niemi, A., "An Extension to Session Initiation Protocol
(SIP) Events for Conditional Event Notification",
draft-ietf-sip-subnot-etags-01 (work in progress),
August 2007.
9.2. Informative References
[W3C.REC-xml-20060816]
Maler, E., Paoli, J., Bray, T., Yergeau, F., and C.
Sperberg-McQueen, "Extensible Markup Language (XML) 1.0
(Fourth Edition)", World Wide Web Consortium
Recommendation REC-xml-20060816, August 2006,
<http://www.w3.org/TR/2006/REC-xml-20060816>.
[RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
Urpalainen Expires June 20, 2008 [Page 12]
Internet-Draft xcap diff event December 2007
[I-D.ietf-simple-partial-notify]
Lonnfors, M., "Session Initiation Protocol (SIP) extension
for Partial Notification of Presence Information",
draft-ietf-simple-partial-notify-09 (work in progress),
February 2007.
Author's Address
Jari Urpalainen
Nokia
Itamerenkatu 11-13
Helsinki 00180
Finland
Phone: +358 7180 37686
Email: jari.urpalainen@nokia.com
Urpalainen Expires June 20, 2008 [Page 13]
Internet-Draft xcap diff event December 2007
Full Copyright Statement
Copyright (C) The IETF Trust (2007).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM 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.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat 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 on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Acknowledgment
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
Urpalainen Expires June 20, 2008 [Page 14]
