Skip to content

fix(options): isolate modern wire semantics and release transfer state - #36

Merged
maikebing merged 5 commits into
masterfrom
codex/coap-options-lifecycle-20261113
Nov 12, 2026
Merged

maikebing merged 5 commits into
masterfrom
codex/coap-options-lifecycle-20261113

Conversation

@maikebing

@maikebing maikebing commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Wire option 19 previously overwrote the header Token, although the current IANA registry assigns it to Q-Block1. This change makes Message.Token the header API, preserves raw option 19/31, and retains the old Token enum alias with an obsolete migration notice. Legacy conversion is available only in explicitly selected historical codecs; RFC 7252 remains the default and its cached endpoint is separate from Draft18.

Per-endpoint option definitions now validate length, strict UTF-8, direction, repetition and value context before events, Matcher and Stack. Unknown or invalid critical messages follow CON/NON/ACK handling; unknown elective values are retained and invalid known elective values are ignored. Proxy requests return 5.05 by default unless a host with an actual proxy deliverer explicitly enables SupportsProxying. Metadata registration does not implement Q-Block or a complete proxy.

Clear, Stop and Dispose retire all endpoint-owned exchanges, including small CON requests and ordinary observations, using their original lifecycle generation. The complete old snapshot releases its Blockwise, Observe and Reliability contexts before the first public callback. Terminal-event dispatch calls all subscribers before reporting aggregated exceptions. Matcher removal atomically checks the expected exchange so an old completion cannot delete a replacement Token/MID/URI mapping. Ordinary unicast success and failure share a single terminal outcome; Observe notifications retain their ongoing behavior.

Validation for final head f0a4982:

  • Windows Release: 404/404 PASS, zero failures or skips, TreatWarningsAsErrors=true.
  • Final COAPALL registry/explicit-codec/endpoint-isolation subset: 23/23 PASS; default library output restored. Earlier individual COAP03/08/12/13 subsets passed 15 each.
  • Owned-source format and staged whitespace checks PASS; existing CRLF/LF is preserved.
  • Default Resource/MVC sample build: zero warnings/errors.
  • Review regressions reproduce endpoint retirement, throwing terminal subscribers, conditional Matcher ownership and release of all Blockwise contexts before callbacks. Original failures and the earlier asynchronous-coordination UNKNOWN are retained in the audit.
  • GitHub CI is checked on this exact head before merge. Real-peer interoperability, NativeAOT execution, new package publication/consumption and device/soak acceptance remain separate, unrun gates.

Compatibility: terminal callback exceptions now appear as a flattened AggregateException after all subscribers run; ordinary nonterminal event dispatch retains its existing contract. Old AddOption(Token, ...) callers must migrate to Message.Token.

Boundaries: Q-Block handlers and bounded multicast collection are not implemented. The existing first-response multicast completion gap is tracked in #37; callback flexibility alone is not advertised as multicast support. Token security/generation (#33), unsigned typed getter range (#34) and long Observe Max-Age (#35) remain open.

Migration: docs/coap-options-compatibility.md.
Source hashes, baseline failures and final evidence: docs/audits/coap-20261113/phase2-review-validation.json and phase2-validation.json.

Closes #28
Closes #29

Refs #23, #33, #34, #35, #37.

Copilot AI balanced review requested due to automatic review settings November 12, 2026 21:20

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Critical lifecycle and matcher-cleanup defects can revive stale requests, leave exchanges active when callbacks throw, and remove replacement exchanges’ mappings; multicast matching also ends after the first response.

4 open issues
What changed in this PR

This PR updates CoAP.NET’s protocol stack to use modern option semantics by default, validate inbound options, and strengthen transfer cleanup.

Changes:

  • Separates header Tokens from raw options 19/31 and confines legacy conversion to explicitly selected codecs.
  • Adds per-endpoint option validation and explicit proxy opt-in.
  • Extends blockwise cleanup and terminal callback handling, with regression tests and migration documentation.
File Description
README.md Links the modern option migration guide.
HANDOFF.md Records delivery scope, validation results, and remaining work.
docs/​coap-standards-roadmap.md Distinguishes historical audit gaps from current changes.
docs/​coap-options-compatibility.md Documents modern semantics, migration, and capability boundaries.
docs/​audits/​coap-20261113/​phase2-validation.json Records validation results, source hashes, and unrun gates.
CoAP.Test/​RegistryOptionTest.cs Tests option metadata and raw option/header Token separation.
CoAP.Test/​OptionTest.cs Replaces deprecated Token-option tests with generic raw-option tests.
CoAP.Test/​OptionSemanticRegressionTest.cs Covers conditional options, Location-Path filtering, and Q-Block rejection.
CoAP.Test/​OptionPolicyTest.cs Tests endpoint validation, custom registration, and proxy policy.
CoAP.Test/​LegacyEndpointIsolationTest.cs Tests independent modern and Draft18 endpoint caches.
CoAP.Test/​LegacyCodecOptionTest.cs Tests explicit legacy Token conversion and ambiguity rejection.
CoAP.Test/​EndpointBlockwiseLifecycleTest.cs Covers endpoint retirement, queued work, and terminal callbacks.
CoAP.Test/​CoapClientTest.cs Replaces fixed asynchronous waits with response signals.
CoAP.Test/​CoapClientProtocolFailureTest.cs Removes the superseded reserved-SZX immediate-failure case.
CoAP.Test/​BlockwiseLifecycleTest.cs Tests cleanup, callback faults, cancellation, and state release.
CoAP.NET/​Stack/​BlockwiseLayer.cs Adds cleanup ownership, terminal guards, and disposal handling.
CoAP.NET/​Spec.cs Isolates legacy conversion and keeps RFC7252 as the default.
CoAP.NET/​OptionType.cs Adds Q-Block names and deprecates the legacy Token alias.
CoAP.NET/​Option.cs Updates Q-Block naming and integer-format metadata.
CoAP.NET/​Net/​CoapOptionRegistry.cs Defines supported options and inbound filtering rules.
CoAP.NET/​Net/​CoapOptionDefinition.cs Defines option constraints and strict UTF-8 validation.
CoAP.NET/​Net/​CoAPEndPoint.cs Integrates option policy, lifecycle guards, and cleanup.
CoAP.NET/​Message.cs Preserves option 19 without modifying the header Token.
CoAP.NET/​CoapClient.cs Coordinates success/failure callbacks and ongoing-response exceptions.
CHANGELOG.md Summarizes compatibility changes, cleanup work, and validation boundaries.

Review effort: Balanced

Comment thread CoAP.NET/Net/CoAPEndPoint.cs Resolved
Comment thread CoAP.NET/Stack/BlockwiseLayer.cs Resolved
Comment thread CoAP.NET/Stack/BlockwiseLayer.cs Resolved
Comment thread CoAP.NET/CoapClient.cs Resolved
@maikebing
maikebing merged commit 3565f49 into master Nov 12, 2026
4 checks passed
@maikebing
maikebing deleted the codex/coap-options-lifecycle-20261113 branch November 13, 2026 04:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants