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@xxxxxxxx https://www.ietf.org/mailman/listinfo/last-call
