Subject: Re: Last Call: <draft-nottingham-rfc5988bis-05.txt> (Web Linking) to Proposed Standard

From: Julian Reschke <[email-masked]>
Date: Thu, 11 May 2017 20:16:54 +0200

Here's my feedback, mainly editorial nits...:

    Additionally, the following rules are included from [RFC3986]: URI
    and URI-Reference; from [RFC6838]: type-name and subtype-name; from
    [W3C.CR-css3-mediaqueries-20090915]: media_query_list; and from
    [RFC5646]: Language-Tag.

That doesn't work, as "_" is not a legal ABNF character.

2.  Links

    In this specification, a link is a typed connection between two
    resources, and is comprised of:

    o  A _link context_,

    o  a _link relation type_ (Section 2.1),

    o  a _link target_, and

    o  optionally, _target attributes_ (Section 2.2).

It might be good to add forward references for "link context" and "link 
target" as well.

    Finally, links are consumed by _link applications_. Generally, an
    application will define the link relation type(s) it uses, along with
    the serialisation(s) that they might occur within.  For example, the
    application "Web browsing" looks for the "stylesheet" link relation
    type in the HTML link serialisation, whereas the application
    "AtomPub" uses the "edit" and "edit-media" link relations.

Actually, one popular browser also looks for the stylesheet link 
relation in the "Link" header field...

    Relation types are not to be confused with media types [RFC6838];

Media types are defined in RFC 2046; RFC 6838 is mainly about media type 
registrations.

    they do not identify the format of the representation that results
    when the link is dereferenced.  Rather, they only describe how the
    current context is related to another resource.

    o  *Reference*: Reference to the document that specifies the link
       relation type, preferably including a URI that can be used to
       retrieve a copy of the document.  An indication of the relevant
       section(s) MAY also be included, but is not required.

s/MAY/can/

    Note that relation types can be registered by third parties
    (including the Expert(s)), if the Expert(s) determine that an
    unregistered relation type is widely deployed and not likely to be
    registered in a timely manner.

maybe s/registered/registed otherwise/?

2.1.1.2.  Registration Request Processing

    Relation types are registered on the advice of a Designated Expert
    (appointed by the IESG or their delegate), with a Specification
    Required (using terminology from [RFC5226]).

s/[RFC5226]/Section 4.1 of [RFC5226]/

2.2.  Target Attributes

    This specification does not attempt to coordinate the name of target
    attributes, their cardinality or use.  Serialisations SHOULD
    coordinate their target attributes to avoid conflicts in semantics or
    syntax.

I'm not sure who's the audience for this SHOULD, and how to implement 
it. For instance, shouldn't this spec do this for the header field 
serialization?

3.  Link Serialisation in HTTP Headers

s/Headers/Header fields/

    This specification defines the link-params "rel", "anchor", "rev",
    "hreflang", "media", "title", "title*", and "type"; see Section 3.2,
    Section 3.3 and Section 3.4.

s/Section 3.2, Section 3.3 and Section 3.4/Sections 3.2, 3.3, and 3.4/

3.1.  Link Target

    Each link-value conveys one target IRI as a URI-Reference (after
    conversion to one, if necessary; see [RFC3987], Section 3.1) inside
    angle brackets ("<>").  If the URI-Reference is relative, parsers
    MUST resolve it as per [RFC3986], Section 5.  Note that any base IRI
    from the message's content is not applied.

Maybe s/base IRI from the message's content/base IRI appearing inside 
the message's content/

3.2.  Link Context

    By default, the context of a link conveyed in the Link header field
    is identity of the representation it is associated with, as defined
    in [RFC7231], Section 3.1.4.1, serialised as a URI.

Broken sentence: "is identity".

    The ABNF for the "anchor" parameter's value is:

      URI-Reference

s/URI-Reference/URI-Reference; Section 4.1 of [RFC3986]/

    Note that depending on HTTP status code and response headers, the
    link context might be "anonymous" (i.e., no link context is
    available).  For example, this is the case on a 404 response to a GET
    request.

I understand this is identical in RFC 5988, but where does this actually 
come from? It basically restricts use of anchor-less link header fields 
2xx responses, right?

3.3.  Relation Type

    The ABNF for the "rel" and "rev" parameters' values is:

      relation-type *( 1*SP relation-type )

    where:

      relation-type  = reg-rel-type | ext-rel-type

Finally I can use this link https://www.youtube.com/watch?v=LbK-g8tKnoc 
in LC feedback!

      reg-rel-type   = LOALPHA *( LOALPHA | DIGIT | "." | "-" )
      ext-rel-type   = URI

s/URI/URI; Section 3 of [RFC3986]/

    Note that extension relation types are REQUIRED to be absolute URIs
    in Link headers, and MUST be quoted if they contain a semicolon (";")

s/headers/header fields/

    or comma (",") (as these characters are used as delimiters in the
    header field itself).

There are more characters legal in URIs but illegal in token -- so maybe 
phrasing it like this can cause confusion. Maybe "MUST be quoted when 
they contain characters not allowed in tokens, such as ...."?

3.4.1.  Serialisation-Defined Attributes

    The ABNF for the "type" parameter's value is:

      type-name "/" subtype-name

(maybe point to https://tools.ietf.org/html/rfc6838#section-4.2 here)

3.5.  Link Header Field Examples

Maybe add an example for multiple Link header field instances in a 
single message?

4.1.  Link HTTP Header Field Registration

    Header field: Link
    Applicable protocol: http
    Status: standard
    Author/change controller:
        IETF  ([email-masked])
        Internet Engineering Task Force
    Specification document(s):
        [RFC&rfc.number;]

s/[RFC&rfc.number;]/this document/

4.2.  Link Relation Type Registry

    Each published document will be at a URL mutually agreed to by IANA
    and the Expert(s), and IANA will set HTTP response headers on them as
    (reasonably) requested by the Expert(s).

Wow. Does IANA know that we want to configure their web server?

5.  Security Considerations

    Link applications ought to consider the attack vectors opened by
    automatically following, trusting, or otherwise using links gathered
    from HTTP headers.  In particular, Link header fields that use the

s/headers/header fields/

    "anchor" parameter to associate a link's context with another
    resource are to be treated with due caution.

    The Link header field makes extensive use of IRIs and URIs.  See
    [RFC3987] for security considerations relating to IRIs.  See
    [RFC3986] for security considerations relating to URIs.  See
    [RFC7230] for security considerations relating to HTTP headers.

s/headers/header fields/

7.1.  Normative References

    [W3C.CR-css3-mediaqueries-20090915]
               Lie, H., Celik, T., Glazman, D., and A. Kesteren, "Media
               Queries", World Wide Web Consortium CR CR-css3-
               mediaqueries-20090915, September 2009,
               <http://www.w3.org/TR/2009/CR-css3-mediaqueries-20090915>.

Need to update to 
<https://www.w3.org/TR/2012/REC-css3-mediaqueries-20120619/>.

    [W3C.REC-html5-20141028]
               Hickson, I., Berjon, R., Faulkner, S., Leithead, T.,
               Navara, E., O&#039;Connor, T., and S. Pfeiffer, "HTML5",
               World Wide Web Consortium Recommendation REC-
               html5-20141028, October 2014,
               <http://www.w3.org/TR/2014/REC-html5-20141028>.

Broken escape in author name.

A.1.  Link Serialisation in HTML

    HTML5 ([W3C.REC-html5-20141028]) Section 4.8 defines modern HTML

"Section 4.8 of HTML5"

    links.  That document links to the Microformats Wiki as a registry;
    over time, the IANA registry ought to mirror its contents, and
    ideally eventually replace it (although that depends on the HTML
    community).

Appendix B.  Algorithm for Parsing Link Headers

    Given a HTTP header field-value "field_value" as a string assuming
    ASCII encoding, the following algorithm can be used to parse it into
    the model described by this specification:

This part is a bit scary -- I don't know how to review it. It might be 
better to have code in an actual programming language, and a set of 
tests for it.

    1.  Let "links" be an empty list.

    2.  Create "link_strings" by splitting "field_value" on ","
        characters, excepting "," characters within quoted strings as per

I have my doubts that people will be able to translate it into actually 
correct code. To detect whether something is inside a quoted-string 
essentially requires running a parser; the prose here suggests that this 
is not necessary.

It also should mention that there might be multiple instances of 
field_value.

---

From: Mark Nottingham <[email-masked]>
Date: Sun, 14 May 2017 17:35:36 +1000

Thanks for the feedback, Julian. I've incorporated into source; responses below where necessary.

> On 12 May 2017, at 4:16 am, Julian Reschke <[email-masked]> wrote:
> 
> It might be good to add forward references for "link context" and "link target" as well.

Context and target are explained directly below the list; they don't have their own sections in the generic model.

> Actually, one popular browser also looks for the stylesheet link relation in the "Link" header field...

True, but that's not specified behaviour, AIUI.

> Media types are defined in RFC 2046; RFC 6838 is mainly about media type registrations.
> 

I did "...not likely to be registered in a timely manner otherwise."

> I'm not sure who's the audience for this SHOULD, and how to implement it. For instance, shouldn't this spec do this for the header field serialization?

The audience is people creating or maintaining serialisations; I've clarified the language.

The header field serialisation has, effectively; it was designed to be compatible with existing serialisations (HTML first, with Atom succeeding it, since Link pre-dated it, even though it wasn't specified).

> s/Section 3.2, Section 3.3 and Section 3.4/Sections 3.2, 3.3, and 3.4/

That's hard to automate; I think we can fix that at the RFC editor stage.

> Maybe s/base IRI from the message's content/base IRI appearing inside the message's content/
> 
> 3.2.  Link Context
> 
> I understand this is identical in RFC 5988, but where does this actually come from? It basically restricts use of anchor-less link header fields 2xx responses, right?

<http://httpwg.org/specs/rfc7231.html#identifying.payload>, referenced just a few paragraphs earlier.

> Finally I can use this link https://www.youtube.com/watch?v=LbK-g8tKnoc in LC feedback!

Source:
  https://github.com/mnot/I-D/issues/33#issuecomment-260825416

Do you have any further suggestions?

> There are more characters legal in URIs but illegal in token -- so maybe phrasing it like this can cause confusion. Maybe "MUST be quoted when they contain characters not allowed in tokens, such as ...."?
> 
> Maybe add an example for multiple Link header field instances in a single message?
> 

We're talking about it. Data, metadata -- what's the difference?

> Need to update to <https://www.w3.org/TR/2012/REC-css3-mediaqueries-20120619/>.
> 
>   [W3C.REC-html5-20141028]

Hmm.

> This part is a bit scary -- I don't know how to review it. It might be better to have code in an actual programming language, and a set of tests for it.

That's not current practice for the intended audience, and shipping code makes it more likely that it will be used as a "reference implementation." This is marked as explicitly non-normative, and the precedence is clear.

It has been reviewed (and improved) by others, FWIW. If we find problems, we do have errata.

> I have my doubts that people will be able to translate it into actually correct code. To detect whether something is inside a quoted-string essentially requires running a parser; the prose here suggests that this is not necessary.

I reluctantly agree. I'll need to rework the algorithm to address this; please stand by.

> It also should mention that there might be multiple instances of field_value.

The algorithm is for parsing a single field-value...

--
Mark Nottingham   https://www.mnot.net/

---

From: Julian Reschke <[email-masked]>
Date: Sun, 14 May 2017 10:03:52 +0200

On 2017-05-14 09:35, Mark Nottingham wrote:
> ...

I was going to say: there are sub sections in Section 3 - but yes, they 
are specific to the header field...

> True, but that's not specified behaviour, AIUI.

<https://www.w3.org/TR/html5/document-metadata.html#the-link-element>:

"HTTP Link: headers, if supported, must be assumed to come before any 
links in the document, in the order that they were given in the HTTP 
message. These headers are to be processed according to the rules given 
in the relevant specifications. [HTTP] [WEBLINK]"

So this refers to RFC 5988, which delegates to the IANA registry, which 
in turn points back to the HTML spec for the definition of the 
"stylesheet" link relation.

To me this sounds like it is well-defined, just not required ("if 
supported").

> That's hard to automate; I think we can fix that at the RFC editor stage.

(hard to automate with markdown? :-)

> Do you have any further suggestions?

Just added to the issue:

-    "_" is not legal in a production name
-    use "/" instead of "|"

> We're talking about it. Data, metadata -- what's the difference?

Operationally?

> I reluctantly agree. I'll need to rework the algorithm to address this; please stand by.

The only way to properly split list supporting field values is to parse 
them according to the grammar for the list items; I don't believe in the 
existence of a shortcut that actually works correctly. Suggesting 
otherwise IMHO will lead to broken implementations for certain edge cases.

> The algorithm is for parsing a single field-value...

Yes, but should we tell the audience that they need to parse *all* field 
values, and combine the result?

Best regards, Julian

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 15 May 2017 11:42:34 +1000

On 14 May 2017, at 6:03 pm, Julian Reschke <[email-masked]> wrote:

> "HTTP Link: headers, if supported, must be assumed to come before any links in the document, in the order that they were given in the HTTP message. These headers are to be processed according to the rules given in the relevant specifications. [HTTP] [WEBLINK]"
> 
> So this refers to RFC 5988, which delegates to the IANA registry, which in turn points back to the HTML spec for the definition of the "stylesheet" link relation.
> 
> To me this sounds like it is well-defined, just not required ("if supported").

https://github.com/mnot/I-D/commit/8e3d4c5167e

> -    "_" is not legal in a production name

Now in the repo, thanks.

>> We're talking about it. Data, metadata -- what's the difference?

We'll see. 

> The only way to properly split list supporting field values is to parse them according to the grammar for the list items; I don't believe in the existence of a shortcut that actually works correctly. Suggesting otherwise IMHO will lead to broken implementations for certain edge cases.

+1

> Yes, but should we tell the audience that they need to parse *all* field values, and combine the result?

OK.

---

From: Julian Reschke <[email-masked]>
Date: Mon, 15 May 2017 06:38:34 +0200

+1

Best regards, Julian

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 16 May 2017 12:37:06 +1000

> On 15 May 2017, at 11:42 am, Mark Nottingham <[email-masked]> wrote:
> 
>>>> 

This is what I currently have:
  https://gist.github.com/mnot/2fb569e7303dbcdde8b27cb7a404a648

I need to get some more eyeballs onto it to make sure it's correct (or at least reasonable). Reviews appreciated. 

Cheers,

---

From: Julian Reschke <[email-masked]>
Date: Wed, 17 May 2017 12:41:37 +0200

> I need to get some more eyeballs onto it to make sure it's correct (or at least reasonable). Reviews appreciated.

I think this goes into the right direction; it's mostly a parser based 
on a relaxed ABNF transformed to prose (which makes me wonder whether 
there's a tool to be written here :-).

Other comments:

1)  "... If it is not present, context_string is the identity of the 
representation carrying the Link header ..." - similar prose is 
elsewhere in the spec - what is "the identity of a representation"?????

2) "Consume the contents up to but not including the first DQUOTE 
character that is not preceded by a "" character" - I assume there's a 
backslash missing here. That said: doesn't work, because it would fail 
for an input such as: "\\" - here, the DQUOTE is preceded by backslash, 
but it's not part of the quoted-pair.

Best regards, Julian

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 18 May 2017 13:22:10 +1000

> On 17 May 2017, at 8:41 pm, Julian Reschke <[email-masked]> wrote:
> 
> I think this goes into the right direction; it's mostly a parser based on a relaxed ABNF transformed to prose (which makes me wonder whether there's a tool to be written here :-).
> 
> Other comments:
> 
> 1)  "... If it is not present, context_string is the identity of the representation carrying the Link header ..." - similar prose is elsewhere in the spec - what is "the identity of a representation"?????

See the linked reference. Would it be better to use "URL" instead of "identity"?

> 2) "Consume the contents up to but not including the first DQUOTE character that is not preceded by a "" character" - I assume there's a backslash missing here. That said: doesn't work, because it would fail for an input such as: "\\" - here, the DQUOTE is preceded by backslash, but it's not part of the quoted-pair.

I've updated to address this.

Thanks,

---

From: Julian Reschke <[email-masked]>
Date: Thu, 18 May 2017 07:02:29 +0200

> See the linked reference. Would it be better to use "URL" instead of "identity"?

URL (or URI).

Goes into the right direction, but doesn't seem to be correct yet:

> 4. While input has content:
>
>     i. If the first character is a backslash ("\"):
>
>         1. Discard the first character.
>
>         2. If there is no more input, return output.
>
>         3. Else, consume the first character and append it to output.
>
>     ii. Else, if the first character is DQUOTE, discard it and return output.

There seems to be missing a step between (i) and (ii) for non-quoted-pairs.

Best regards, Julian

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 18 May 2017 16:25:16 +1000

See changes:
  https://github.com/mnot/I-D/commit/143403a2e7e37

In situ:
  https://mnot.github.io/I-D/rfc5988bis/

> On 18 May 2017, at 3:02 pm, Julian Reschke <[email-masked]> wrote:
>