Re: [Gen-art] [Last-Call] Genart last call review of draft-ietf-httpbis-semantics-16

Lars Eggert <lars@eggert.org> Fri, 11 June 2021 11:44 UTC

Return-Path: <lars@eggert.org>
X-Original-To: gen-art@ietfa.amsl.com
Delivered-To: gen-art@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id D79223A34B6; Fri, 11 Jun 2021 04:44:38 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.099
X-Spam-Level:
X-Spam-Status: No, score=-2.099 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=eggert.org
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id vlTt5__Gy7WA; Fri, 11 Jun 2021 04:44:34 -0700 (PDT)
Received: from mail.eggert.org (mail.eggert.org [91.190.195.94]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 7992D3A34B4; Fri, 11 Jun 2021 04:44:30 -0700 (PDT)
Received: from smtpclient.apple (unknown [212.68.24.84]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.eggert.org (Postfix) with ESMTPSA id 0624D60031C; Fri, 11 Jun 2021 14:44:20 +0300 (EEST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=eggert.org; s=dkim; t=1623411861; bh=3EpRHUEPaFFQ8SfYMVHfdEPmYD9DDMK5w/b1cohucdc=; h=From:Subject:Date:In-Reply-To:Cc:To:References; b=zTcILyzQUfcZdUZKAFj5btztHZXSFXgn5D3vLGERXli7viihH0Y0ANmMSqdEl6OXI i3qf56FJTotHpFYa5+M+TOYhefAUX89gH4fWKq9vHW+GR6IsmCQOhhXrbaneB0EL2J mq/fgiUSOxQBK8UBsLwztnwk1JxDO2pha+D/jpdg=
From: Lars Eggert <lars@eggert.org>
Message-Id: <22C17ECD-B3C0-4D3F-91E7-190FBD40A246@eggert.org>
Content-Type: multipart/signed; boundary="Apple-Mail=_F727F0DA-5943-4A53-A5BA-F2BB1B19546D"; protocol="application/pgp-signature"; micalg=pgp-sha512
Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.100.0.2.22\))
Date: Fri, 11 Jun 2021 14:44:20 +0300
In-Reply-To: <162328627348.12750.15937727767340024943@ietfa.amsl.com>
Cc: General Area Review Team <gen-art@ietf.org>, last-call@ietf.org, draft-ietf-httpbis-semantics.all@ietf.org, ietf-http-wg@w3.org
To: Dale Worley <worley@ariadne.com>
References: <162328627348.12750.15937727767340024943@ietfa.amsl.com>
X-MailScanner-ID: 0624D60031C.A1020
X-MailScanner: Found to be clean
X-MailScanner-From: lars@eggert.org
Archived-At: <https://mailarchive.ietf.org/arch/msg/gen-art/BkrUJTw-MMJYx51n-6RHLT6NhGI>
Subject: Re: [Gen-art] [Last-Call] Genart last call review of draft-ietf-httpbis-semantics-16
X-BeenThere: gen-art@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: "GEN-ART: General Area Review Team" <gen-art.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/gen-art>, <mailto:gen-art-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/gen-art/>
List-Post: <mailto:gen-art@ietf.org>
List-Help: <mailto:gen-art-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/gen-art>, <mailto:gen-art-request@ietf.org?subject=subscribe>
X-List-Received-Date: Fri, 11 Jun 2021 11:44:39 -0000

Dale, thank you for your review, which I hope will see a response soon. I have entered a No Objection ballot for this document.

Lars


> On 2021-6-10, at 3:51, Dale Worley via Datatracker <noreply@ietf.org> wrote:
> 
> 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]
> 
> 
> 
> --
> last-call mailing list
> last-call@ietf.org
> https://www.ietf.org/mailman/listinfo/last-call