[Gen-art] Genart last call review of draft-ietf-httpbis-semantics-16

[Dale Worley via Datatracker <[e-mail]>]

Reviewer: Dale Worley
Review result: Ready with Nits

I am the assigned Gen-ART reviewer for this draft. The General Area
Review Team (Gen-ART) reviews all IETF documents being processed
by the IESG for the IETF Chair.  Please treat these comments just
like any other last call comments.

For more information, please see the FAQ at

<https://trac.ietf.org/trac/gen/wiki/GenArtfaq>.

Document:  review-draft-ietf-httpbis-semantics-16
Reviewer:  Dale R. Worley
Review Date:  2021-06-09
IETF LC End Date:  2021-06-10
IESG Telechat date:  2021-06-17

Summary:

    This draft is basically ready for publication, but has editorial
    nits that should be fixed before publication.

Nits/editorial comments:

4.  Identifiers in HTTP

The single sentence under section 4 seems to apply only to section
4.1.  It probably should be moved to 4.1 and combined with its current
first sentence.

4.1.  URI References

   Unless otherwise indicated, URI references
   are parsed relative to the target URI (Section 7.1).

Possibly worth amplifying to "... the target URI of the request".
(Which is unambiguous because every protocol element is within either
a request or a response, and each response is associated with a
single request.)

4.3.3.  https origins

   A server might be unwilling to serve as the origin for
   some hosts even when they have the authority to do so.

This seems badly phrased.  Perhaps this was intended:

   A server might be unwilling to serve requests for a particular
   origin even if it has the authority to do so.

--

   Note, however, that the above is not the only means for obtaining an
   authoritative response, nor does it imply that an authoritative
   response is always necessary (see [Caching]).

You probably intend to add here that also, the server MAY not respond
to such a TCP connection.  That is, the above "MAY" permits the client
to attempt a TCP connection but does not require the server to respond
to it (especially if it is HTTP/3-only).

4.3.4.  https certificate verification

   rather than one matching the dynamic URI's origin server
   identifier.

I think "dynamic URI's" is not quite what is intended.  I think the
meaning is that the presented certificate will not match "the address
and hostname of the server" (which is configured into the client in
some special way, rather than being determined from the request URI).
In that case, better text would be

   rather than one matching the server's address and hostname.

--

   If the certificate is not valid for the URI's origin server, a user
   agent MUST either notify the user (user agents MAY give the user an
   ...

This largely duplicates the last paragraph of section 3.5.  Would it
be possible to simply reference that section?  Or to split off the
last paragraph as its own section 3.5.1?  Or perhaps reduce this
paragraph to

   If the certificate is not valid for the URI's origin server, a user
   agent MUST either notify the user, terminate the connection with a
   bad certificate error, or take steps described in section 3.5.

That is, give the "naive summary" here and refer to the carefully
qualified alternatives in section 3.5.

5.2.  Field Lines and Combined Field Value

   The field value for "Example-
   Field" is a list with three members: "Foo", "Bar", and "Baz".

This isn't quite correct, as the preceding text doesn't speak of
generating a "list" in the sense of a programming language datatype,
but rather it speaks of generating a character string which is the
combined field value, which has the syntax "list".  So the proper
wording is

   The field value for "Example-Field" is "Foo, Bar,Baz".

Note also that the first comma is followed by a space, as that is how
it is presented in the first field line, while the second comma is
not, as it comes from the processing "field line values
... concatenated in order, with each field line value separated by a
comma".

(Of course, that distinction is irrelevant, as the semantics of list-based
fields is constructed so that OWS after commas is insignificant, but
that design principle of httpbis-semantics hasn't been introduced yet,
so the discussion at this point should not depend on it if that can be
avoided.)

5.3.  Field Order

   For consistency, use comma SP.

Better to clarify,

   For consistency, using comma SP is RECOMMENDED.

5.6.1.2.  Recipient Requirements

   Then the following are valid values for example-list (not including
   the double quotes, which are present for delimitation only):

     "foo,bar"
     "foo ,bar,"
     "foo , ,bar,charlie"

Given the distinction between what a sender is permitted to generate
and a recipient is required to accept, "valid" is not clearly defined
here.  It could be clarified:

   A sender may only generate the first of the following values, but a
   recipient must accept all of these values (not including the double
   quotes, which are present for delimitation only):

...

   In contrast, a recipient must reject the following values, since at least
   one non-empty element is required by the example-list production:

5.6.2.  Tokens

Given the second paragraph, titling this section "Tokens and
Delimiters" would be better.

5.6.7.  Date/Time Formats

It seems like it's worth changing "preferred format" to "RECOMMENDED
format" in this section.

6.  Message Abstraction

   a headers lookup table of key/value pairs for extending that

I think replacing "lookup table" with "set" in this section would
improve its reading.  (Strictly, there is no word that conveys the
meaning we want, as (1) two header field lines with exactly the same
contents are possible, and are not redundant, (2) header field lines
with the same name ore ordered, but (3) header field lines with
different names are not ordered.)  But "lookup table" sounds like it
is prescribing an implementation.

6.4.  Content

   HTTP messages often transfer a complete or partial representation as
   the message _content_: a stream of octets sent after the header
   section, as delineated by the message framing.

I think you want to add "Specifically, the content reflects the data
without any specified Transfer-Encoding, but with any specified
Content-Encoding.  (The encodings listed in Content-Encoding are a
characteristic of the representation of the resource data.)"  Then
remove the first sentence of the next paragraph.

6.5.1.  Limitations on use of Trailers

   The presence of the keyword "trailers" in the TE header field

Perhaps s/keyword/token/

7.1.  Determining the Target Resource

   For example, Appendix of
   [Messaging] defines how a server determines the target URI of an
   HTTP/1.1 request.

It appears the correct reference is actually section 3.3 of [Messaging].

7.4.  Rejecting Misdirected Requests

   Before performing a request, a server decides whether or not to
   provide service for the target URI via the connection in which the
   request is received.

This sentence is correct but seems hard to read.  Perhaps

   Before performing a request, a server decides whether or not to
   provide service for the target URI to requests received via the
   connection.

7.6.  Message Forwarding

   However, recipients cannot rely on
   incremental delivery of partial messages, ...

Actually, "However, senders and recipients cannot rely ..."

7.7.  Message Transformations

   A proxy that transforms the
   content of a 200 (OK) response can inform downstream recipients that
   a transformation has been applied by changing the response status
   code to 203 (Non-Authoritative Information) (Section 15.3.4).

It seems like this "can" should be changed to MAY, SHOULD, or MUST,
depending on how strict we want this to be.

7.8.  Upgrade

   For those
   purposes, it is more appropriate to use a 3xx (Redirection) response
   (Section 15.4).

Better to say:

   For those purposes, a 3xx (Redirection) response (Section 15.4) can
   be used.

since Upgrade won't work in this situation.

9.2.1.  Safe Methods

An additional example of a safe method affecting the resource is a web
page containing a "this page has been fetched NNN times" counter.  In
this case, a GET of the page will cause the resource retrieved by
future GETs to be different, but in the context, that difference is
considered to be non-significant.

   A user agent SHOULD distinguish between safe and unsafe methods when
   presenting potential actions to a user, such that the user can be
   made aware of an unsafe action before it is requested.

It might be well to reference the last paragraph of section 3.5 here.

9.3.1.  GET

   A successful response reflects
   the quality of "sameness" identified by the target URI.  

This is hard to understand without more detail.  Perhaps

  Successful responses to multiple GET requests for the same target
  URI show a particular quality of "sameness" which is identified by
  the target URI.

Examples of this are (1) a URI for the current weather conditions at a
particular location, (2) a URI for the recorded weather conditions at
a particular location and particular past time, and (3) a URI for the
predicted weather conditions at a particular location and particular
future time.  The response contents to successive GETs of any one of
these URIs can differ, but they have the "same" meaning in a
particular sense.  However, each URI exhibits a different sense of
"sameness".

9.3.4.  PUT

   An origin server SHOULD verify that the PUT representation is
   consistent with any constraints the server has for the target
   resource that cannot or will not be changed by the PUT.

This is difficult to read -- I believe "that cannot ..." modifies the
3rd preceding noun, "constraints", but it took analysis to determine
that.  Perhaps expand it to:

   An origin server SHOULD verify that the PUT representation is
   consistent with any constraints the server has for the target
   resource (considering any changes in the constraints that may
   be caused by PUT itself).

10.1.4.  TE

   The "TE" header field in a request can be used to indicate that the
   sender will not discard trailer fields when it contains a "trailers"
   member, as described in Section 6.5.

Less awkwardly:

   The "TE" header field in a request, when it contains a "trailers"
   token, indicates that the sender will not discard trailer fields
   that it receives, as described in Section 6.5.

10.2.  Response Context Fields

   The remaining response header fields provide more information about
   the target resource for potential use in later requests.

This sentence seems to be redundant.  Also, it's not clear what
"remaining" references.

11.4.  Credentials

   ... based upon a challenge received in a response
   (possibly at some point in the past).

The parenthesized phrase seems redundant, because if the challenge was
received in a response it must have been received at some point in the
past.

11.6.1.  WWW-Authenticate

I always have trouble remembering which headers are used in requests
and which in responses.  So in

   The "WWW-Authenticate" header field indicates the authentication
   scheme(s) and parameters applicable to the target resource.

I would prefer it start "The "WWW-Authenticate" header field in a
response ...", which parallels how the other authentication headers
are introduced.

11.6.3.  Authentication-Info

   A proxy forwarding a response is not allowed to modify the field
   value in any way.

Probably s/is not allowed to/MUST NOT/.

12.1.  Proactive Negotiation

   (hoping
   to avoid the round trip delay of a subsequent request if the "best
   guess" is good enough for the user)

This is somewhat awkward as the syntax does not tell that "if the best
guess ..." applies to "avoid" or to "delay".  Perhaps better is

   (when the "best guess" is good enough for the user, this avoids the
   round trip delay of a subsequent request)

12.2.  Reactive Negotiation

   A server might choose not to send an initial representation, other
   than the list of alternatives, and thereby indicate that reactive
   negotiation by the user agent is preferred.

It seems to me that this must be "... and thereby require reactive
negotiation by the user agent."

12.4.1.  Absence

   For each of the content negotiation fields, a request that does not
   contain the field implies that the sender has no preference on that
   axis of negotiation.

"axis" is not used elsewhere in this document.  I suspect "dimension"
is intended.

      |  *Note:* Sending these header fields makes it easier for a

I believe this is "A user agent sending these header fields ...",
which isn't the default reading, since the nearest noun that can
"send" is "a server".

13.1.5.  If-Range

   Note that the If-Range comparison by exact match, including when the
   validator is an HTTP-date, differs from the "earlier than or equal
   to" comparison used when evaluating an If-Unmodified-Since
   conditional.

Possibly easier to read as:

   Note that the If-Range comparison is by exact match, including when the
   validator is an HTTP-date, and so differs from the "earlier than or equal
   to" comparison used when evaluating an If-Unmodified-Since
   conditional.

13.2.1.  When to Evaluate

   Note that protocol extensions can modify the conditions under which
   revalidation is triggered.  For example, the "immutable" cache
   directive (defined by [RFC8246]) instructs caches to forgo
   revalidation of fresh responses even when requested by the client.

The relationship of this paragraph to the section is unclear.  It
appears to deal with the processing by a cache (which is a topic of
this section), but the operation of "revalidation" is not defined at
this point.  It is also surprising that [Caching] is not referenced
here, although when I check, "immutable" is indeed not mentioned in
[Caching].  Perhaps

   Note that protocol extensions can modify the conditions under which
   preconditions are evaluated or the consequences of their evaluation.
   For example, the "immutable" cache 
   directive (defined by [RFC8246]) instructs caches to forgo
   forwarding requests even when requested by the client.

13.2.2.  Precedence of Preconditions

   Any extension to HTTP that defines additional conditional request
   header fields ought to define its own expectations regarding the
   order for evaluating such fields in relation to those defined in this
   document and other conditionals that might be found in practice.

This could be shortened to

   Any extension to HTTP that defines additional conditional request
   header fields ought to define the
   order for evaluating such fields in relation to those defined in this
   document and other conditionals that might be found in practice.

15.3.7.  206 Partial Content

   A sender that generates a 206 response with an If-Range header field
   SHOULD NOT generate other representation header fields beyond those
   required, because the client already has a prior response containing
   those header fields.

If I read the document correctly, If-Range cannot be used in a
response, and this should start "A sender that generates a 206
response to a request with an If-Range header field ...".

15.5.21.  422 Unprocessable Content

What is the correct response code if the request content does not
conform to its Content-Type?  That is, comparing to the example in
this section, if the Content-Type is XML but the content octets are
not syntactically correct XML.

16.2.2.  Considerations for New Status Codes

   The definition of a new status code ought to specify whether or not
   it is cacheable.  Note that all status codes can be cached if the
   response they occur in has explicit freshness information; however,
   status codes that are defined as being cacheable are allowed to be
   cached without explicit freshness information.  Likewise, the
   definition of a status code can place constraints upon cache
   behavior.  See [Caching] for more information.

I think the term used for cacheability of status codes is
"heuristically cacheable", as the cacheability of a response code can
always be overridden by Cache-Control.  Compare with section 15.1.

16.4.2.  Considerations for New Authentication Schemes

   *  The credentials carried in an Authorization header field are
      specific to the user agent and, therefore, have the same effect on
      HTTP caches as the "private" Cache-Control response directive
      (Section 5.2.2.7 of [Caching]), within the scope of the request in
      which they appear.

Should this information be copied in, say, section 11.4?  I suppose
that only 5.2.2.7 of [Caching] is needed.  But if this is a general
property of Authorization header fields, it seems more proper to
describe the general property in 11.4 and then here point to 11.4 and
say "Therefore, new authentication schemes that choose not to carry
credentials in the Authorization header field..."

[END]