Subject: [core] quick feedback on CoAP-04

From: Peter Saint-Andre <[email-masked]>
Date: Tue, 25 Jan 2011 21:19:59 -0700

Overall this spec is looking solid, so thanks to the authors,
contributors, and implementers!

Here are just a few quick comments based on my review this evening
before the conference call tomorrow. I've had a chance to read only the
first half of the spec (through the end of Section 5, with a quick look
at Section 6). I'll work to complete a more detailed review in the near
future.

1. The early sections talk about the need to limit packet size, but
Figure 4 looks like it violates those considerations with duplicate data:

   |                  |
   |   ACK [0xbc91]   |
   |  4.04 Not Found  |
   |   (Token 0x72)   |
   |   "Not found"    |
   |<-----------------+
   |                  |

This makes it appear that the server returns a packet containing both
"4.04 Not Found" and "Not found". :)

2. Section 2 states:

   CoAP makes use of HTTP GET, PUT, POST and DELETE methods, with the
   semantics specified in Section 5.8.

However, are we in fact using those HTTP methods exactly as they are
defined in draft-ietf-httpbis-p2-semantics (or RFC 2616)? E.g., the
description of CoAP GET in Section 5.8.1 of our spec is conceptually
similar to the descriptions of HTTP GET in Section 9.3 of RFC 2616 and
Section 7.3 of draft-ietf-httpbis-p2-semantics-12, but there are enough
differences to perhaps confuse readers.

See also Section 5.1:

   CoAP supports the basic methods of GET, POST, PUT, DELETE, which are
   easily mapped to [i.e., not exactly the same as] HTTP.

3. We might want to say a little bit about reasons why we would update
the "Version" field from 1 to 2 (e.g., making changes that are not
backward compatible).

4. Section 5.2 states:

   However, there is no generic Response Code
   indicating success, so a Response Code in the Success class that is
   unrecognized by an end-point can only be used to determine that the
   request was successful without any further details.

How is that different from handling of a generic code for success?

5. It is unclear in Section 5.2.2. how the client correlates a deferred
response with its original request (given that the server chooses a new
Message ID when sending the response). Perhaps a forward pointer to the
token stuff in Section 5.3 would help?

6. Section 5.4.5 states:

   Options are identified by an option number.  Odd numbers indicate a
   critical option, while even numbers indicate an elective option.

Is it expected that applications will be able to depend on that convention?

7. Section 5.5 states:

   A response with a code indicating a Client or Server Error SHOULD
   include a brief human-readable diagnostic message as payload,
   explaining the error situation.  This diagnostic message MUST be
   encoded using UTF-8 [RFC3629], more specifically using Net-Unicode
   form [RFC5198].  The Content-Type Option has no meaning and SHOULD
   NOT be included.

Human-readable to whom? Do we need language tags? Typically anything
that's human-readable needs to identify the language.

8. Are the URI handling rules in Section 6 entirely consistent with RFC
3986?

(More to follow...)

Peter

-- 
Peter Saint-Andre
https://stpeter.im/

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 26 Jan 2011 07:45:45 +0100

Hi Peter,

another set of very useful comments!
Let me just quickly point out a direction for solving these, so we can turn them into tickets.

> Figure 4 looks like it violates those considerations with duplicate data:

It's probably not useful to add diagnostic information to a 404.

> that's human-readable needs to identify the language.

This is intended as diagnostic information, not for real humans (who would need language tags), but for software engineers (who need to speak the language of the RFC anyway).
Like what you would put on an HTTP status line.
We need to make this clearer.  But maybe we have to develop some examples first.
(We also need to discuss diagnostic information in "empty" messages such as RST; this would be a technical change.)
(Is it even the right way to carry around diagnostics in otherwise unused payload?
We could use an option, but there goes another byte.)

>   easily mapped to [i.e., not exactly the same as] HTTP.

Make clearer that CoAP methods are almost, but not entirely unlike HTTP.

> the "Version" field from 1 to 2 (e.g., making changes that are not

Yes.

> How is that different from handling of a generic code for success?

We just don't have a generic one, i.e. all class 2 codes are currently more specific than "success".
We could change that.
2.00 was just kind of attractive for GET "this is a representation of the resource you requested".
OTOH, we already have had a request for a "neutral" success code for POST.

> token stuff in Section 5.3 would help?

Yes.

> Is it expected that applications will be able to depend on that convention?

It is not a convention, it is a feature of the protocol.
Make that clearer in the text.

> 8. Are the URI handling rules in Section 6 entirely consistent with RFC

That was the intention (no ticket until we know where we failed :-)

Gruesse, Carsten