Repository navigation
fix(options): isolate modern wire semantics and release transfer state - #36
Merged
Merged
Conversation
There was a problem hiding this comment.
🟡 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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.


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:
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.