Subject: Gen-ART Review of draft-ietf-sip-xcapevent-03

From: "Spencer Dawkins" <[email-masked]>
Date: Fri, 19 Sep 2008 14:16:38 -0500

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/

   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.

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/

   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.

   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/?

   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//

   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...

   the subscribed XCAP attribute content(s).  The notifier MUST thus

Spencer (technical): this MUST seems strange... is it really derived from
the previous sentence?

   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.

   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/

   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//?

   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/

   Root URI value, for example.  A future specification(s) MAY be

Spencer (technical): not a 2119 MAY

   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?

   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...

   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.

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.

_______________________________________________
Ietf mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/ietf

---

From: Jari Urpalainen <[email-masked]>
Date: Mon, 22 Sep 2008 14:55:16 +0300

Thanks Spencer, comments in-line

> Spencer (clarity): s/with the aid of which clients can/which clients can use
ok

> Spencer (technical): Is this "are based on the XCAP-Diff format"? If not, I
right.

> Spencer (clarity): s/except polling/beyond polling/
ok

> Spencer (clarity): "a collection content" reads oddly, unless this is a
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."

> Spencer (clarity): s/shown/included in the notification/?
right.

> Spencer (clarity): s/but//
ok

> they were "MUST and/or MUST and/or MUST", you could require one of the three
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.  

> Spencer (technical): this MUST seems strange... is it really derived from
"thus" was misleading.

> Spencer (technical): almost certainly not a 2119 MAY.
ok.

> Spencer (clarity): s/with the/in/
ok

> Spencer (technical): s/either//?
right

> Spencer (clarity): s/somehow/with/
ok

> Spencer (technical): not a 2119 MAY
ok

> invert the sentence, if that's what it IS saying?
inverted the sentence.

> Spencer (technical): probably not 2119 MAY...
ok

>    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..."

>    required bandwidth usage to extremes.
ok

thanks, Jari