draft-ietf-httpbis-client-hints-00 feedback

[Julian Reschke <[e-mail]>]

Hi there,

see below feedback; in document order, sorry for that.

(I'm happy to provide pull requests for the nits...)

Best regards, Julian

-- snip --


Abstract

    An increasing diversity of Web-connected devices and software
    capabilities has created a need to deliver optimized content for each
    device.

    This specification defines a set of HTTP request header fields,
    colloquially known as Client Hints, to address this.  They are
    intended to be used as input to proactive content negotiation; just
    as the Accept header allows clients to indicate what formats they

NIT: s/header/header field/ (multiple times in document)

    prefer, Client Hints allow clients to indicate a list of device and
    agent specific preferences.

The spec should be clear whether it's about *clients* or *user agents* 
(I believe it is about user agents, right?)


1.  Introduction

    One way to infer some of these capabilities is through User-Agent
    (UA) detection against an established database of client signatures.

NIT: reference User-Agent header field definition

    A popular alternative strategy is to use HTTP cookies to communicate
    some information about the client.  However, this approach is also
    not cache friendly, bound by same origin policy, and imposes
    additional client-side latency by requiring JavaScript execution to
    create and manage HTTP cookies.

NIT: reference cookie spec

    This document defines a set of new request header fields that allow
    the client to perform proactive content negotiation [RFC7231] by

NIT: make reference more specific


1.1.  Notational Conventions

    This document uses the Augmented Backus-Naur Form (ABNF) notation of
    [RFC5234] with the list rule extension defined in [RFC7230], Appendix
    B. It includes by reference the DIGIT rule from [RFC5234]; the OWS,
    field-name and quoted-string rules from [RFC7230]; and the parameter
    rule from [RFC7231].

NIT: most of these do not seem to be used.

2.  Client Hint Request Header Fields

    This document defines a selection of Client Hint request header
    fields, and can be referenced by other specifications wishing to use
    the same syntax and processing model.

NIT: true, but there doesn't seem to be a common syntax after all. A 
leftover from earlier versions?

2.1.  Sending Client Hints

    Clients control which Client Hint headers and their respective header
    fields are communicated, based on their default settings, user

That really doesn't parse...

    configuration and/or preferences.  The user may be given the choice
    to enable, disable, or override specific hints.

Please avoid lowercase RFC2119 terms. In this case, "can" seems to be 
right.

    The client and server, or an intermediate proxy, may use an opt-in
    mechanism to negotiate which fields should be reported to allow for
    efficient content adaption.

Same here.

2.2.  Server Processing of Client Hints

    Servers MAY respond with an optimized response based on one or more
    received hints from the client.  When doing so, and if the resource

No need for a MAY here. It's a statement of fact.

    is cacheable, the server MUST also emit a Vary response header field
    ([RFC7234]), and optionally Key ([I-D.ietf-httpbis-key]), to indicate
    which hints were used and whether the selected response is
    appropriate for a later request.

a) make "Vary" reference more specific

b) this really repeats a RFC 7234 requirement, so I'd avoid the "MUST" 
here; just emphasize that this requirement is there because of RFC 7234.

    Further, depending on the used hint, the server MAY also need to emit
    additional response header fields to confirm the property of the

...can...

    response, such that the client can adjust its processing.  For
    example, this specification defines "Content-DPR" response header
    field that MUST be returned by the server when the "DPR" hint is used
    to select the response.

Please have the normative requirement just once (down where DPR is 
defined).

2.2.1.  Advertising Support for Client Hints

    Servers can advertise support for Client Hints using the Accept-CH
    header or an equivalent HTML meta element with http-equiv attribute.

Nit: reference HTML spec.

    When a client receives Accept-CH, it SHOULD append the Client Hint
    headers that match the advertised field-values.  For example, based
    on Accept-CH example above, the client would append DPR, Width,
    Viewport-Width, and Downlink headers to all subsequent requests.

Not sure whether really is a SHOULD. Is a client that chooses to 
implement only one of the hints in violation of the spec?

2.2.2.  Interaction with Caches

    When selecting an optimized response based on one or more Client
    Hints, and if the resource is cacheable, the server MUST also emit a
    Vary response header field ([RFC7234]) to indicate which hints were
    used and whether the selected response is appropriate for a later
    request.

(see above)

      Vary: DPR

    Above example indicates that the cache key should be based on the DPR
    header.

s/should be based/needs to include/

    Client Hints MAY be combined with Key ([I-D.ietf-httpbis-key]) to
    enable fine-grained control of the cache key for improved cache
    efficiency.  For example, the server MAY return the following set of
    instructions:

s/MAY/can/

In general, as "Key" is a separate spec and fully optional, it might be 
better to move the discussion specific to "Key" into a separate section.


3.  The DPR Client Hint

    The "DPR" header field is a number that, in requests, indicates the
    client's current Device Pixel Ratio (DPR), which is the ratio of
    physical pixels over CSS px of the layout viewport on the device.

What does it mean in responses then? It might be simpler to say "request 
header field" (this applies to most of the definitions)

Also include a reference to "CSS px".

      DPR = 1*DIGIT [ "." 1*DIGIT ]

    If DPR occurs in a message more than once, the last value overrides
    all previous occurrences.

It might be good to state that it's invalid to include it multiple times 
(applies to most definitions).

3.1.  Confirming Selected DPR

    The "Content-DPR" header field is a number that indicates the ratio
    between physical pixels over CSS px of the selected image response.

...response header field...

      Content-DPR = 1*DIGIT [ "." 1*DIGIT ]

    DPR ratio affects the calculation of intrinsic size of image
    resources on the client - i.e. typically, the client automatically
    scales the natural size of the image by the DPR ratio to derive its
    display dimensions.  As a result, the server must explicitly indicate
    the DPR of the selected image response whenever the DPR hint is used,
    and the client must use the DPR value returned by the server to
    perform its calculations.  In case the server returned Content-DPR

These are MUSTs, right?

    value contradicts previous client-side DPR indication, the server
    returned value must take precedence.

Same here...

    Note that DPR confirmation is only required for image responses, and
    the server does not need to confirm the resource width as this value
    can be derived from the resource itself once it is decoded by the
    client.

As we have a normative requirement here, we probably need to state what 
an "image resource" exactly is.


4.  The Width Client Hint

    The "Width" header field is a number that, in requests, indicates the
    resource width in physical px (i.e. intrinsic size of an image).  The
    provided physical px value is a number rounded to the largest
    smallest following integer (i.e. ceiling value).


      Width = 1*DIGIT

    If the resource width is not known at the time of the request or the
    resource does not have a display width, the Width header field may be
    omitted.  If Width occurs in a message more than once, the last value
    overrides all previous occurrences.

It took me some time to understand that this is the width the user agent 
intends to use to display the resource. Maybe this could be rephrased.

It might also be good to say why there's no matching "Height" field.


5.  The Viewport-Width Client Hint

    The "Viewport-Width" header field is a number that, in requests,
    indicates the layout viewport width in CSS px.  The provided CSS px+

Need minimal explanation (or ref) about what a "layout viewport" is.


6.  The Downlink Client Hint

    The "Downlink" header field is a number that, in requests, indicates
    the client's maximum downlink speed in megabits per second (Mbps), as
    defined by the "downlinkMax" attribute in the W3C Network Information
    API.

Needs reference (already present in editor's copy).

8.  Examples

    For example, given the following request headers:


      DPR: 2.0
      Width: 320
      Viewport-Width: 320

    The server knows that the device pixel ratio is 2.0, that the
    intended display width of requested resource is 160 CSS px (320

s/of/of the/

    physical pixels at 2x resolution), and that the viewport width is 320
    CSS px.


9.  Security Considerations

    Client Hints defined in this specification do not expose any new
    information about the user's environment beyond what is already
    available to, and may be communicated by, the application at runtime
    via JavaScript - e.g. viewport and image display width, device pixel
    ratio, and so on.

    However, implementors should consider the privacy implications of
    various methods to enable delivery of Client Hints - see "Sending
    Client Hints" section.  For example, sending Client Hints on all

Section #...

    requests may make information about the user's environment available
    to origins that otherwise did not have access to this data (e.g.
    origins hosting non-script resources), which may or not be the
    desired outcome.  The implementors may want to provide mechanisms to
    control such behavior via explicit opt-in, or other mechanisms.
    Similarly, the implementors should consider how and whether delivery
    of Client Hints is affected when the user is in "incognito" or
    similar privacy mode.

(may, should, etc...)

10.  IANA Considerations

    o  Header field name: DPR
    o  Applicable protocol: HTTP
    o  Status: standard
    o  Author/Change controller: IETF
    o  Specification document(s): [this document]

...insert section # (applies to all definitions)

11.  Normative References

    [I-D.ietf-httpbis-key]
               Fielding, R. and m. mnot, "The Key HTTP Response Header
               Field", draft-ietf-httpbis-key-00 (work in progress),
               October 2015.

...the autogenerated ref is broken :-)