nanocoap: Move application functionality to nanocoap sock

[kb2ma]

Contribution description

#11098 added the ability for a single (nano|g)coap resource to respond to a subtree of request URIs. Open PR #11436 additionally will provide a mechanism to lookup into a nested set of resources to handle requests within that subtree. This mechanism includes a new function and a subtree handler struct in the base nanocoap library. However, gcoap already has the ability to specify multiple sets of handlers via its listener mechanism.

The location of the additional capability for 11436 in the base nanocoap library means gcoap must evaluate whether or how to incorporate the new nanocoap subtree handlers. In this case, the new mechanism is not required. This conflict illustrates how "nanocoap" really is a combination of two tools:

• a base CoAP library, useful for any application level tool like gcoap
• an application level tool itself

nanocoap as an application already includes the nanocoap sock module for high level functions to send and receive a message. So, this PR extends the split of these two roles by moving more application level functionality to the nanocoap sock module. Specifically, this includes these methods and structs:

• coap_build_reply()
• coap_block2_build_reply()
• coap_handle_req()
• coap_tree_handler()
• coap_reply_simple()
• coap_well_known_core_default_handler()
• coap_resources[]
• coap_resources_numof

With this change, nanocoap sock independently can add the subtree handler functionality in 11436. This relocation allows nanocoap to innovate without causing a conflict with gcoap. At the same time, if this new mechanism develops into a generally worthwhile feature, it can be migrated to the base nanocoap library in the future.

Testing procedure

No new functionality, so ensure nothing is broken:

• nanocoap unit tests
• nanocoap_cli test
• nanocoap_server example

Issues/PRs references

See description.

[chrysn]

As I understand this PR, RIOT's CoAP would be divided in nanocoap-message, nanocoap-socket and gcoap, where both the latter use the former to manipulate their messages. When the gcoap user needs to interact with nanocoap-message, they should not be presented with functions inapplicable to them. (Indeed that'd have saved me some time).

Looking at the built documentation, I don't think this is complete though; see inline comments, and:

• "Server path matching" is a prominent part in the nanocoap-message overview. As there is only one coap_resource_t method, it might be more suitable to describe there (after all, this is now only a tool method).

What I still can't fully judge is whether the separation is precise. Would anything go wrong if someone used, for example, coap-build_reply in a gcoap handler?

[chrysn]

The whole section could now use a name that indicates it's about the messages

[chrysn]

Suggested change

	* also provides functions to support sending and receiving messages, such as
	* also provides helpers for use before sending of after receiving messages, such as

[kb2ma]

Added this suggestion to #12231 since it's an improvement to generic nanocoap.

[kb2ma]

Would anything go wrong if someone used, for example, coap-build_reply in a gcoap handler?

For this specific example, yes you can do this, and you must use the Buffer API for the rest of this response. Also, you must manually add any Observe option to the response. See gcoap_resp_init().

I respond in more detail in a comment on 12201. IMO for a user the choice of gcoap vs. nanocoap sock is challenging enough. Layering on documentation to selectively use the Buffer API in gcoap or the Packet API in nanocoap requires qualifications that would be difficult to explain clearly and simply.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. If you want me to ignore this issue, please mark it with the "State: don't stale" label. Thank you for your contributions.

[kaspar030]

would it make sense to split this into nanocoap/client.h and nanocoap/server.h?

[bergzand]

I agree with this, but I don't mind leaving this to a follow up PR. @kb2ma What do you think?

[kb2ma]

would it make sense to split this into nanocoap/client.h and nanocoap/server.h?

I like the 'name substitution' aspect. In other words, get rid of "sock" from the name, which is descriptive but overlaps with the name of the messaging stack networking API. The use of 'client' and 'server' imply endpoint messaging without really conflicting with gcoap. It's possible that nanocoap.h might split someday for other reasons, but I think we can manage the distinction from the client/server headers. The module documentation title can change from 'Nanocoap Sock' to 'Nanocoap Client/Server' or something like that.

In terms of implementation files, remember that the client/server split can be murky. A client might send a NON request but receive a CON response and have to manage retries. Neither gcoap or nanocoap supports that now, but it's out there.

[edit -- Client/Server example is wrong -- a client already manages retries for a CON request. OTOH, a server might want to send an immediate ACK to a request, and then send a separate response confirmably.]

[kb2ma]

I agree with this, but I don't mind leaving this to a follow up PR. @kb2ma What do you think?

That works for me. Let's make the migration out of nanocoap.(h|c) itself as one step, and then the group that works more closely with it can split it up however works best.

[kb2ma]

Rebased for your reviewing pleasure. Also moved coap_tree_handler(), introduced in #13687, to nanocoap sock.