Thanks Spencer, comments in-line
On Fri, 2008-09-19 at 14:16 -0500, ext Spencer Dawkins wrote:
I have been selected as the General Area Review Team (Gen-ART)
reviewer for this draft (for background on Gen-ART, please see
http://www.alvestrand.no/ietf/gen/art/gen-art-FAQ.html).
Please resolve these comments along with any other Last Call comments
you may receive.
Document: draft-ietf-sip-xcapevent-03
Reviewer: Spencer Dawkins
Review Date: 2008-09-19
IETF LC End Date: 2008-10-02
IESG Telechat date: not known
Summary: this document is on the right track for publication as a Proposed
Standard but a few changes are required before publication. The document has
a number of 2119 issues. There are a few areas where I thought I understood
the text but had to guess at its meaning. I flagged these as clarity
comments unless I thought they were disguising a technical issue.
Comments: "clarity" comments included here are for the editor's convenience
and are not actually part of the Gen-ART review.
Abstract
This document describes an "xcap-diff" SIP event package for the SIP
Event Notification Framework, with the aid of which clients can
Spencer (clarity): s/with the aid of which clients can/which clients can use
to/
ok
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.
Spencer (technical): Is this "are based on the XCAP-Diff format"? If not, I
don't understand.
right.
1. Introduction
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
Spencer (clarity): s/except polling/beyond polling/
ok
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.
There are three basic features that this event package enables with
the XCAP-Diff [I-D.ietf-simple-xcap-diff] change notification format.
Firstly, it can list a collection [RFC4918] content of an XCAP
Spencer (clarity): "a collection content" reads oddly, unless this is a
technical term.
perhaps it was programmer thinking... changed to "Firstly, it can list
the URI references of XCAP documents from a collection [RFC 4918]
located on an XCAP server."
server, which means in practice listing the URI references of XCAP
documents from a collection. This is important when a subscriber is
doing an initial synchronization or a comparison of existing server
resources to the locally cached XCAP documents, for example. The
version-history of document comparisons are based on the strong
entity tag (ETag) values of XCAP documents which are also indicated
with the XCAP-Diff format.
Secondly, this event package can signal whenever a change is
happening in those resources. The changes can be reported with three
ways. The simplest model is that only document creations, updates
and removals are indicated. The actual contents of those documents
are not shown and the subscriber uses the (HTTP) RFC 2616 [RFC2616]
Spencer (clarity): s/shown/included in the notification/?
right.
protocol for a retrieval of document contents. The two more complex
modes allow the changes of documents to be indicated straightaway
with the XML-Patch-Ops [I-D.ietf-simple-xml-patch-ops] semantics
inside the XCAP-Diff [I-D.ietf-simple-xcap-diff] format. A client
can then apply a conditional patch to locally cached documents based
on the strong ETag values of documents. The most complex model
produces the smallest documents but it doesn't necessarily show the
full HTTP version-history information unlike the other, but typically
Spencer (clarity): s/but//
ok
more verbose one.
Lastly, XML element or attribute contents (XCAP components) can be
received "in-band", that is straight within the XCAP-Diff
notification format. For example, an XCAP element content can be
requested and indicated without the need of a separate HTTP GET
request. If this requested node either exists or is later created or
modified, the notification body indicates its content. And
similarly, the removals of subscribed XCAP components are reported,
for example after a successful HTTP DELETE request.
4. XCAP-Diff Event Package
4.1. Overview of Operation With Basic Requirements
The first notification of the subscription MUST always contain the
URI references of the subscribed, existing documents and/or SHOULD
contain the subscribed XCAP element content(s) and/or MUST contain
Spencer (technical): "MUST and/or SHOULD and/or MUST" seems complex - and
why is the SHOULD a SHOULD? As stated, you can violate the SHOULD and do
none of the three, and things should still work - is that the intent? If
they were "MUST and/or MUST and/or MUST", you could require one of the three
choices...
yep, "or"'s are totally wrong here, since you must include the
subscribed content with the exception of not indicating the element
content when the size is unreasonable for the transport.
the subscribed XCAP attribute content(s). The notifier MUST thus
Spencer (technical): this MUST seems strange... is it really derived from
the previous sentence?
"thus" was misleading.
always support XCAP component subscriptions. The subsequent
notifications MAY contain patches to these documents. The notifier
MUST support the simplest change notification model, but the XML-
Patch-Ops diff-generation is RECOMMENDED to implement. The
subscriber MAY control how the notifier will signal the changes of
Spencer (technical): almost certainly not a 2119 MAY.
ok.
documents. How this can be done, will be shown later in this
document.
Whenever a change in a resource or an XCAP component content is
indicated inside the XCAP-Diff [I-D.ietf-simple-xcap-diff] format,
the subscriber MUST have read privilege to that particular resource.
4.3. 'diff-processing' Event Package Parameter
With aid of the optional "diff-processing" event header parameter the
subscriber directs the notifier how to apply the "XML diffing
process" or in other words, how the notifier SHOULD indicate change
notifications of documents. The possible values are "no-patching",
"xcap-patching" and "aggregate" with the increasing complexity order.
Spencer (clarity): s/with the/in/
ok
If the subscription does not contain this additional "diff-
processing" parameter, the notifier SHOULD send all individual
changes so that the client receives the full (HTTP) ETag change
history of a document. In other words, "xcap-patching" is the
default operational mode of a notifier. Note that the "no-patching"
mode does not necessarily either indicate the full HTTP ETag change
Spencer (technical): s/either//?
right
history.
4.4. SUBSCRIBE Bodies
It is anticipated that the XCAP server will be collocated with the
SIP notifier, so the subscriber MAY use relative XCAP R-URIs. This
means that the notifier has then been provisioned somehow the XCAP
Spencer (clarity): s/somehow/with/
ok
Root URI value, for example. A future specification(s) MAY be
Spencer (technical): not a 2119 MAY
ok
written for the more complex use-cases, this memo describes only the
most simple one.
4.7. Notifier Generation of NOTIFY Requests
During the initial subscription the notifier MUST first resolve the
requested XCAP resources. If the subscribed body contains elements
or attributes that it doesn't understand, they MUST be ignored by the
notifier. If there are superfluous resource 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, MUST be included in the XCAP-
Spencer (technical): I'm not sure whether this is saying "MUST NOT include
if authenticated user does not have read privilege" or not - could you
invert the sentence, if that's what it IS saying?
inverted the sentence.
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.
While with the most complex patching mode "aggregate" the bandwidth
usage is the most efficient, it introduces other challenges. The
initial synchronization MAY fail with rapidly changing resources,
because the "aggregate" mode doesn't necessarily indicate the full
version-history of a document and the base XCAP protocol does not
support version-history retrievals of documents. Secondly, when new
documents are created into the subscribed collections and the
notifier is "aggregating" patches, the same issue MAY occur. In a
Spencer (technical): probably not 2119 MAY...
ok
corner-case, the notifier may not be able to provide patches with the
XML-Patch-Ops [I-D.ietf-simple-xml-patch-ops] semantics. Therefore,
if the notifier has to temporarily disable diff-generation and send
only the URI references of some changed documents to the subscriber,
it MUST continue with the "xcap-patching" mode afterwards for these
resources, if the initial subscription also started with the "xcap-
patching" mode.
4.8. Subscriber Processing of NOTIFY Requests
During re-subscriptions the received state of all previous resources
MUST be stamped as stale except when a conditional
Spencer (clarity): s/except when/until/?
[I-D.ietf-sip-subnot-etags] re-subscription is successful. Then the
current state of resources MUST be preserved unless the subscribed
URI-list has changed, i.e. the resource's state MUST then be fetched
for example from some local cache.
right, this is confusing. Changed to : "During unconditional
re-subscriptions the received state of all previous resources MUST be
stamped as stale. However, if a conditional re-subscription is
successful the current state of resources MUST be preserved unless..."
7. Security Considerations
Denial-of-Service attacks against the notifiers deserve a special
mentioning. Subscriptions to a long list of URIs MAY be too process-
intensive. The "pending" subscriptions to un-existing documents or
Spencer (clarity): s/un-existing/non-existent/?
XCAP components impose the same challenge as well as the diff-
generation algorithms, at least when they try to optimize the
required bandwidth usage to extremes.
ok
thanks, Jari
_______________________________________________
Ietf mailing list
Ietf(_at_)ietf(_dot_)org
https://www.ietf.org/mailman/listinfo/ietf