Subject: Re: [core] Review of draft-ietf-core-comi-09

From: Ivaylo Petrov <[email-masked]>
Date: Mon, 4 May 2020 10:42:03 +0200

Hello Klaus,

I apologize for the delay and thank you for your review! It was really
useful for me and for the draft I believe. Please find my answers below
(prefixed with [IP]). Please note that the diff after handing your comments
is available at [1].

Best regards,
Ivaylo

[1]:
https://tools.ietf.org/rfcdiff?url1=https://tools.ietf.org/id/draft-ietf-core-comi.txt&url2=https://core-wg.github.io/comi/draft-ietf-core-comi.txt

On Mon, Apr 13, 2020 at 1:04 PM Klaus Hartke <[email-masked]> wrote:

> Section 2.4: The document seems to use the terms "content format" as a
> synonym for "content type". A content format is the combination of a
> content type (which is the combination of a media type with specific
> values for the media type's parameters) with a content coding. An
> example for a media type is "text/plain", for a content type
> "text/plain;charset=utf-8", and for a content format
> "text/plain;charset=utf-8" combined with "gzip". I think you mean
> content type, right?
>

[IP]: It seems to me that you are right, therefore I have changed content
format to content type in all places where such a change seemed necessary.
Please do not hesitate to let me know if I have missed any place or if I
have misunderstood you.

Section 2.4: In the table, all the media types incorrectly have a leading
> "/".
>
> Section 4: It's not okay to mandate or recommend specific paths like
> </c> and </s>. Not even with a lower-cased "recommended". It's fine to
> define a path structure after the "root path" of the application and
> use an example path in examples, but implementers should not be
> restricted or discouraged in any way to choose a different path (see
> BCP 190). The best choice is probably to use a long, not very nice
> looking path like </path/to/the/data/store/X9?k="eth0">, so that
> implementers immediately get the idea to pick a shorter path
> themselves :-)
>

[IP]: I believe I captured what was suggested here, but please check if
that is indeed the case.

Section 4: The document specifies the API in terms of the CoAP
> Uri-Query option a lot. The Uri-Query option is just the way how the
> query string of the request URI is encoded in CoAP, though. It would
> be better to specify the API in term of query strings and not to
> mention the Uri-Query option.
>
> Section 4.1: It's unclear if a client should send the query string
> <?k=0> or <?k="0"> (with quotes, as shown in the table) for a Boolean
> value.
>

[IP]: I believe now this is clear. It is now also clarified that 0 maps to
false and 1 to true (which might not be what a person using a lot of bash
would expect).

Section 4.1: It's unclear if the int2str function returns "291" (5
> characters) or "291" (3 characters, typographically set in quotes).
>
> Section 4.2.2: It's unclear if a client should send the query string
> <?d=t> or <?d= 't'> (with a space and single quotes, as shown in the
> indented paragraph).
>
Section 4.2.3.1: It's unclear why a client needs to send the query
> string <?k="eth0"> instead of <?k=eth0>. The table in section 4.1
> seems to say that a string `key` is written as `key`, not as `"key"`.
> Can a `key` contain `"` characters itself and, if yes, how are those
> escaped?
>

[IP]: It should be clear now that it is without the quotes (for the three
points).

Section 4.5: If I understand this correctly, this enables getting
> events by appending these to an internal "log file" and exposing the
> latest few entries of the log file as the resource </s>. This resource
> can be observed, so that if new entries are appended, the resource
> changes its state and the client gets notifications. Correct? It might
> be worth pointing out that this scheme does guarantee delivery of all
> entries in the log file to the client. It might also be a good idea to
> remind implementers of what happens when the size of the last few
> entries is greater than the MTU.
>
> Section 4.5: The last paragraph says "To check that the client is
> still alive, the server MUST send Confirmable Message periodically."
> That's what RFC 7641 already specifies. Please don't make normative
> statements that repeat (or contradict) what RFC 7641 says. :-)
>

[IP]: As you pointed out, this is clearly specified in RFC 7641, so I
removed it from this document.

Klaus
>
> _______________________________________________
> core mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/core
>

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 4 May 2020 11:18:28 +0200

On 2020-05-04, at 10:42, Ivaylo Petrov <[email-masked]> wrote:
> [IP]: I believe I captured what was suggested here, but please check if that is indeed the case.

This problem of course comes up repeatedly in a number of WGs.
Here is an example from a position on this as taken in the OAuth WG: <https://mailarchive.ietf.org/arch/msg/oauth/QH7Mc2gDjONLi58c2g_5nt0UL44>

I don’t think that filling all examples with noise such as /path/to/the/data/store is really helpful.
I would prefer to have most examples use the IYDHABI (*) paths, with only a few alternative paths (all different!) used in some examples.

BCP 190 asks to ensure the server has a choice, not that all servers must make different choices.

Grüße, Carsten

(*) “if you don’t have a better idea”™

---

From: Ivaylo Petrov <[email-masked]>
Date: Mon, 4 May 2020 17:20:57 +0200

If I am not mistaken, Carsten, your suggestion is to mostly use the same
paths ("/c", "/s") and just have a few examples with different paths. Do
you have an opinion about the wording - do I call the "default" path an
example path (keep this currently text unchanged), do I call them suggested
paths, so that it is clear that people are absolutely free to choose
something else, do we write recommended path with lower case - something
that Klaus does not seem to consider acceptable, or maybe there is a
different option here?

Klaus, is using mostly, but not always, the suggested paths in the examples
a good option for you?

Thanks,
Ivaylo

On Mon, May 4, 2020 at 11:18 AM Carsten Bormann <[email-masked]> wrote:

> Here is an example from a position on this as taken in the OAuth WG: <
> https://mailarchive.ietf.org/arch/msg/oauth/QH7Mc2gDjONLi58c2g_5nt0UL44>
>
> I don’t think that filling all examples with noise such as
> /path/to/the/data/store is really helpful.
> I would prefer to have most examples use the IYDHABI (*) paths, with only
> a few alternative paths (all different!) used in some examples.
>

---

From: Klaus Hartke <[email-masked]>
Date: Mon, 4 May 2020 20:11:22 +0200

Ivaylo Petrov wrote:
> I have changed content format to content type in all places where such a change seemed necessary. Please do not hesitate to let me know if I have missed any place or if I have misunderstood you.

Hmm... I think in section 2.4 you're actually talking about media
types, not content types.

(I know it's confusing! Have a look at
https://tools.ietf.org/html/draft-bormann-core-media-content-type-format-01)

> [IP]: I believe I captured what was suggested here, but please check if that is indeed the case.

Hmmm... maybe </path/to/the/data/store/X9?k=eth0> wasn't the best
idea. Some examples now overflow the page width. And it's a bit
difficult to see where the free-to-choose path segments end and the
standardized path segments start.

Maybe </...coreconf-path.../X9?k=eth0>?

BTW, in examples I think <example.com/something> should be
<coap://example.com/something> or <coaps://example.com/something>.
<example.com/something> looks like a relative URI where the first path
segment happens to contain a dot.

In see in some tables and examples </c> still being used. Is that
intentional? I think it would be better to use the same path prefix
everywhere consistently. (At least the text should point out what
free-to-choose path segments are used in examples.)

> [IP]: I believe now this is clear. It is now also clarified that 0 maps to false and 1 to true (which might not be what a person using a lot of bash would expect).

The text now says:

    o The method int2str() is used to convert an integer value to a
       decimal string. For example, int2str(\x01\x23) returns the three-
       character string "291" (the quotes are added for readability, but
       they are not part of the payload).

Why does int2str now take a byte string as input?

And I think one of "the three-character string "291"" or "(the quotes
are added for readability, but they are not part of the payload)" is
enough, you don't need both :-)

Proposal:

    o The method int2str() is used to convert an integer value to a
       decimal string. For example, int2str(0x0123) return the three-
       character string "291".

The text now says on Booleans:

    o The boolean representations (0) and (1) are the single character
       strings U+0030 and U+0031, where false maps to (0) and true maps
       to (1).

Why not just something like this?

    o The boolean values false and true are represented as the single-character
       strings "0" and "1" respectively.

Then the text now says:

    The resulting key strings are joined using commas between two
    consecutive key values to produce the value of the 'k' parameter.

That's a good clarification.

    The string value of the 'k' parameter is encoded in a Uri-Query as
    specified in [RFC7252] section 6.5.

It seems after "Uri-Query", the word "option" is missing. I think I'd
just omit this sentence, though. It should be clear that query
parameters are encoded as Uri-Query options in CoAP, no?

Klaus