Last Call Review of draft-snell-http-prefer-14
review-snell-http-prefer-14-genart-lc-thomson-2012-09-21-00

Lucky you.  I am the assigned Gen-ART reviewer for this draft. For
background on Gen-ART, please see the FAQ at
  <

http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>.

Please resolve these comments along with any other Last Call comments
you may receive.

Document: draft-snell-http-prefer-14
Reviewer: Martin Thomson
Review Date: 2012-09-21
IETF LC End Date: 2012-10-12

Summary: This document is in pretty good shape.  I have a concern over
how Prefer: wait might be implemented that I believe needs to be
addressed prior to publication as Proposed Standard.  There are also a
number of additional concerns, though nothing particularly serious.

Major issues:

Section 3.4 specifies timing requirements that a server has to act
upon with no good way of gaining the information it needs.  It assumes
clock synchronization. Given that terrible clock synchronization is
the default mode of operation for internet hosts, this seems to be a
poor choice.

In any case, this design forces a server to wait less than the allowed
time in all cases, but gives the server no good information to choose
an appropriate time adjustment.  A server has to assume that the
client has already expended some period waiting.  Assuming that the
client is going to abandon the request at the identified time, then
the server is obliged to wait less than the entire period, lest the
response be wasted.  Even if we assume that clocks are synchronized,
the resolution of Date and wait are capped at a second, so worst case
we have a 1 second window of uncertainty on when the request was sent.
 This is worse if there are clock errors, particularly if the client
clock runs ahead of the server.

I can't see how I would implement this feature so that it behaves
reliably for arbitrary hosts.

On the other hand, the client has the ability to make its own
determination about clock synchronization and network transit delays.
A single request with wait=0 would provide a good measurement of total
non-server delays, without any quantization noise (Date is rounded or
trimmed to the second, which makes this determination difficult).  The
client could then adjust the value of the wait preference to account
for what it learns, with the server being able to then concentrate on
the time elapsed between receipt and sending.  Clock differences are
then irrelevant.

Minor comments:

In Section 3.2:

   When honoring the "return-representation" preference, the server MUST
   include a Content-Location header field specifying the URI of the
   resource representation being returned.

This is a requirement that could be inadvertently violated by servers.
 This really isn't what you are intending here.  The idea is to ensure
that the returned representation doesn't get mistaken for a
representation of the request URI, *when it is not*.  This does not
require 2119 language to convey, though I would agree that a reminder
is necessary here.  How about:

   The returned representation might not be a representation for the
effective request
   URI [[this is the term du jour, I believe]] when the request
affects another resource.
   The Content-Location header can be used to identify the URI of the returned
   representation.

(I'd note that return-representation is less useful for PUT than POST
or PATCH.  You don't mention PATCH at all.)

In Sections 3.2 and 3.3, the mutual exclusivity of these parameters is
handled differently to the strict/lenient parameters.  Instead of all
the 2119 stuff, how about:

   The "return-minimal" and "return-representation" preferences are
   mutually exclusive directives.  A request that contains both preferences
   can be treated as though neither were specified.

Alternatively, did you consider specifying a single preference here?
i.e., Prefer: return=minimal and Prefer: return=representation

Section 3.5, is it useful to observe that the "strict" preference is
useful for ensuring that all aspects of a request are handled, so that
recoverable errors don't result in important parts of a request being
"missed" by a server?

Did you consider a single preference here?  i.e., Prefer:
processing=strict or Prefer: processing=lenient

Regarding Section 3.5, which do we assume to be the existing behavior
for a server?  strict or lenient?

I'd ask an IANA considerations expert to look at Section 4.1.  Did you
want something other than the strict letter of "Specification
Required"?

Nits:

The wording of Section 2.1 is a little contorted.  The second
paragraph is a single sentence.  "event just potentially" is a little
redundant.  Suggest a reword to cover just the key points:
 - Prefer is not intended to affect content negotiation.
 - If a preference could affect what a cache stores or how it stores
it [httpbis-p6], then the server MUST use Vary: Prefer.  This applies
even if the request does not include Prefer.
Caution is always good, but advising its application doesn't improve
the probability of it being applied.

Example 3 in Section 2.2 implies semantics for the undefined "status"
argument.  Doing this begs the question about whether this should have
been specified.  Rather than invite such questions, try using a
generic argument with a nonsensical name.  (Priority in the previous
example is OK, because it's inherently meaningless anyway.)

You have a few references that aren't really necessary.  I don't see
much relevance in httpbis-p7, for example.