net/unicoap: Gardening 01: RFC 7252 PDU Fixes and Corrections by carl-tud · Pull Request #23084 · RIOT-OS/RIOT

carl-tud · 2026-11-07T21:13:43Z

This PR introduces support for extended tokens (https://www.rfc-editor.org/info/rfc8974/#name-extended-tokens), fixes missing ACKs from reliable resources, reduces overhead when ACKing and RSTing, and moves PDU message header definitions into a private C header.

Testing procedure

make -C tests/unittests -j tests-unicoap flash term

Issues/PRs references

Preparation for #23074 and #22277

Declaration of AI-Tools / LLMs usage:

AI-Tools / LLMs that were used are:

Claude Opus 5.5 helped write unit tests, then fixed things like excessive buffers and naming myself
- TIL: you can write [upper .. lower] in designated initialisers
- FYI: After having already written the extended token logic, I asked Claude to do it -- and it produced spaghetti code with like 100 different magic numbers and unnecessarily nested ifs.

carl-tud · 2026-11-07T21:17:15Z

@@ -1314,8 +1335,10 @@ static inline ssize_t unicoap_pdu_build_rfc7252(uint8_t* pdu, size_t capacity,
                                                const unicoap_message_properties_t* properties)
 {
    ssize_t res = 0;
-
-    if ((res = unicoap_pdu_build_header_rfc7252(pdu, capacity, message, properties)) < 0) {
+    if ((res = unicoap_pdu_build_header_rfc7252(pdu, capacity, message, properties)) < 0 ||
+        unlikely(!message)
+    ) {
+        /* If failed, return. Also, if no message, there're no options and no payload, so return. */


Purpose: be able to build PDU without needing to allocate a message structure, which can be larger than the actual on-the-wire PDU we're trying to create. Would be kinda laughable if a helper struct was bigger than the actual on-the-wire PDU...

carl-tud · 2026-11-07T21:18:12Z

+    /* Require allocated message struct unless it's an empty message. This saves memory at the call
+     * site when sending an (empty) ACK or RST. */
+    assert(packet->message ||
+           _get_type(packet) == UNICOAP_TYPE_ACK ||
+           _get_type(packet) == UNICOAP_TYPE_RST);


Same purpose here.

carl-tud · 2026-11-07T21:19:10Z

+static int _acknowledge_or_reset(unicoap_packet_t* packet, unicoap_rfc7252_message_type_t type)
 {
-    packet->message->code = UNICOAP_CODE_EMPTY;
-    packet->message->options = NULL;
-    packet->message->payload = NULL;
-    packet->message->payload_size = 0;
-
-    packet->properties.token = NULL;
-    packet->properties.token_length = 0;
-
-    return (int)_build_and_send_pdu(packet, NULL);
+    /* This is all faster than going through the PDU builder for an empty message. And it saves us
+     * stack allocations that we'd need to prepare for an arbitrary message (more iolist structs and
+     * bigger header buffer for additional token. */
+    unicoap_rfc7252_header_t empty_message = {
+        .version = UNICOAP_COAP_VERSION_1,
+        .code = UNICOAP_CODE_EMPTY,
+    };
+
+    iolist_t vector = {
+        .iol_base = &empty_message,
+        .iol_len = sizeof(empty_message)
+    };
+
+    unicoap_rfc7252_header_set_message_id(&empty_message, _get_id(packet));
+    unicoap_rfc7252_header_set_type(&empty_message, type);
+
+    /* We do not reconnect here for messaging-layer-only PDUs (empty ACKs and RSTs).
+     * Reason: If we send an ACK or RST that means we got a message before. This implies
+     * there was a DTLS session. RFC 7252 mandates ACKs and RSTs must be sent within the
+     * same epoch. A new DTLS session always leads to a new epoch. So sending an ACK or RST
+     * after reconnecting is pointless. Hence, we do not need to call _connect here and can
+     * just send, possibly getting an error from the DTLS transport layer if there's no session. */
+    return _sendv(&vector, packet->remote, packet->local, _packet_get_dtls_session(packet));


Faster than going through the PDU builder, allocating iolists, a scratch buffer, etc. The message we're trying to send is 4 bytes, so let's not be silly.

carl-tud · 2026-11-07T21:19:48Z

+        if (_get_type(packet) == UNICOAP_TYPE_CON) {
+            MESSAGING_7252_DEBUG(UNICOAP_MESSAGE_ID_FORMAT "have not ACKed yet\n", _get_id(packet));
+            assert(_state._unacknowledged_packet == NULL);
+            _state._unacknowledged_packet = packet;
+            /* TODO: Deferred responses (proxy) require space for more than one outstanding ACK. */
+        }


This is safe because state access is synchronised by an event_queue_t.

carl-tud · 2026-11-07T21:20:28Z

-            unicoap_message_t* message = packet->message;
-            unicoap_message_t m = *packet->message;
-            packet->message = &m;
            _acknowledge(packet);
-            packet->message = message;


overhead: q.e.d.

carl-tud · 2026-11-07T21:21:56Z

@@ -0,0 +1,207 @@
+/*


Basically, I can see people wanting to do some CoAP PDU trickery in the future, and providing a header here that exists but is hidden prevent's me from having that headache in the future.

riot-ci · 2026-11-07T21:30:36Z

Murdock results

❌ FAILED

a5bb29f fixup! token bit width

Success	Failures	Total	Runtime
6290	1	13599	05m:02s

Build failures (1)

Application	Target	Toolchain	Runtime (s)	Worker
examples/networking/coap/unicoap_client	atxmega-a1u-xpro	gnu	2.53	mobi5

Artifacts

carl-tud added 6 commits November 7, 2026 22:01

net/unicoap/rfc7252: Ack CON requests before separate response

716c5bb

net/unicoap/rfc7252: Without message, build empty message

8d84d48

net/unicoap: Check endpoint pointer equivalence

2b7aa52

net/unicoap/rfc7252: use header struct as message for ACK/RST

d54d676

net/unicoap/rfc7252: use bit-field header struct

5bf9fc5

fixup! net/unicoap/rfc7252: new pdu API

5bcb043

carl-tud requested a review from mguetschow November 7, 2026 21:13

carl-tud requested review from Teufelchen1 and miri64 as code owners November 7, 2026 21:13

github-actions Bot added Area: network Area: Networking Area: tests Area: tests and testing framework Area: sys Area: System labels Nov 7, 2026

carl-tud mentioned this pull request Nov 7, 2026

net/unicoap: tracking: Unified and Modular CoAP Stack #21389

Open

8 of 22 tasks

carl-tud commented Nov 7, 2026

View reviewed changes

carl-tud added 3 commits November 7, 2026 22:25

net/unicoap/rfc7252: Support extended tokens

751028d

tests/unittests/unicoap: Test extended tokens

57fcba6

fixup! net/unicoap/rfc7252: Use new PDU API

021d3eb

carl-tud force-pushed the unicoap-gardening-01-rfc7252 branch from 924cd88 to 021d3eb Compare November 7, 2026 21:25

carl-tud requested a review from leandrolanzieri as a code owner November 7, 2026 21:25

carl-tud requested review from MrKevinWeiss and jia200x as code owners November 7, 2026 21:25

github-actions Bot added the Area: Kconfig Area: Kconfig integration label Nov 7, 2026

carl-tud added the CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR label Nov 7, 2026

carl-tud added 2 commits November 7, 2026 22:33

net/unicoap/rfc7252/dtls: Return -ENOTCONN

02fe50f

fixup! token bit width

a5bb29f

carl-tud removed request for MrKevinWeiss, Teufelchen1, jia200x, leandrolanzieri and miri64 November 8, 2026 08:38

carl-tud mentioned this pull request Nov 8, 2026

net/unicoap: get rid of state locking #23079

Open

carl-tud marked this pull request as draft November 8, 2026 19:34

carl-tud removed the request for review from mguetschow November 8, 2026 19:35

Navigation Menu

Repository navigation

net/unicoap: Gardening 01: RFC 7252 PDU Fixes and Corrections - #23084

net/unicoap: Gardening 01: RFC 7252 PDU Fixes and Corrections#23084
carl-tud wants to merge 11 commits into
RIOT-OS:masterfrom
carl-tud:unicoap-gardening-01-rfc7252

carl-tud commented Nov 7, 2026 •

edited

Loading

Uh oh!

carl-tud Nov 7, 2026

Uh oh!

carl-tud Nov 7, 2026

Uh oh!

carl-tud Nov 7, 2026

Uh oh!

carl-tud Nov 7, 2026

Uh oh!

carl-tud Nov 7, 2026

Uh oh!

carl-tud Nov 7, 2026 •

edited

Loading

Uh oh!

riot-ci commented Nov 7, 2026 •

edited

Loading

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

carl-tud commented Nov 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Testing procedure

Issues/PRs references

Declaration of AI-Tools / LLMs usage:

Uh oh!

carl-tud Nov 7, 2026

Choose a reason for hiding this comment

Uh oh!

carl-tud Nov 7, 2026

Choose a reason for hiding this comment

Uh oh!

carl-tud Nov 7, 2026

Choose a reason for hiding this comment

Uh oh!

carl-tud Nov 7, 2026

Choose a reason for hiding this comment

Uh oh!

carl-tud Nov 7, 2026

Choose a reason for hiding this comment

Uh oh!

carl-tud Nov 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

riot-ci commented Nov 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Murdock results

Artifacts

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

carl-tud commented Nov 7, 2026 •

edited

Loading

carl-tud Nov 7, 2026 •

edited

Loading

riot-ci commented Nov 7, 2026 •

edited

Loading