Repository navigation
fix!: escape keys in local reference pointers - #60
Conversation
Keys containing "/" or "~" were registered and referenced unescaped, so a spec-correct pointer such as "#/channels/user~1signedup" missed the workspace and was resolved from the raw document into a separate copy of the channel. Unescaped pointers only resolved because both sides skipped escaping. The workspace now registers every component, channel, channel message and server under its escaped pointer, and the 2.x reader escapes the keys of every reference it builds. Names recovered from references (2.x message keys, 2.x channel servers and security requirement names) are taken from the parsed pointer, so they come back unescaped. This keeps 2.x and 3.x reading, writing, upgrading and downgrading intact for such keys. BREAKING CHANGE: a local reference to a key containing "/" or "~" must escape it as "~1" or "~0" (RFC 6901). The unescaped form no longer resolves. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
obfuscan reportStatus: No findings.
No suspicious obfuscation or backdoor patterns were found in the scanned diff. |
|
No actionable comments were generated in the recent review.
 |
| Layer / File(s) | Summary |
|---|---|
JSON Pointer token utilities src/ByteBard.AsyncAPI/JsonPointer.cs, test/ByteBard.AsyncAPI.Tests/JsonPointer_Should.cs |
JsonPointer adds EscapeToken and TryFromUriFragment. ToString uses the shared token-escaping method. |
Reference registration and V2 reading src/ByteBard.AsyncAPI/AsyncApiWorkspace.cs, src/ByteBard.AsyncAPI.Readers/V2/* |
Workspace locations and V2 reader-created references escape keys. Message references use the final unescaped pointer token when parsing succeeds. |
Reference serialization and cross-version tests src/ByteBard.AsyncAPI/Models/AsyncApiChannel.cs, src/ByteBard.AsyncAPI/Models/References/AsyncApiSecuritySchemeReference.cs, test/ByteBard.AsyncAPI.Tests/Models/EscapedReferenceKeys_Should.cs |
V2 channel and security serialization derive names from parsed pointers. Tests cover reference resolution, serialization round trips, and version upgrades and downgrades. |
Priority:
Estimated code review effort: 3 (Moderate) | ~20 minutes
Change: Bug fix
Possibly related PRs
- ByteBardOrg/AsyncAPI.NET#57: Changes the same V2 channel server-reference serialization behavior in
AsyncApiChannel. - ByteBardOrg/AsyncAPI.NET#56: Introduces the
JsonPointerparser contract used by this change.
Suggested reviewers: bielu
Merge Risk: 
74c41
-
No confirmed issue blocks merging after normal checks.
Pre-merge checks: 
-
Check name Status Explanation Resolution Docstring Coverage Docstring coverage is 17.86% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 28 functions across 10 files. Write docstrings for the functions missing them to satisfy the coverage threshold. -
Check name Status Explanation Title check The title "fix!: escape keys in local reference pointers" matches the main change. The PR makes the workspace and the 2.x reader escape keys containing "/" or "~" in local JSON Pointer references (RFC… Description check The description covers the problem, the fix, and the breaking change. It explains that keys containing "/" or "~" were registered and referenced unescaped, and that the workspace now registers compone… Linked Issues check Check skipped because no linked issues were found for this pull request. Out of Scope Changes check Check skipped because no linked issues were found for this pull request. Full details: Title check
-
Explanation
The title "fix!: escape keys in local reference pointers" matches the main change. The PR makes the workspace and the 2.x reader escape keys containing "/" or "~" in local JSON Pointer references (RFC 6901). The "!" marks the breaking change, since unescaped local references no longer resolve. The title is concise and specific, and it names the primary behavior change.
Full details: Description check
-
Explanation
The description covers the problem, the fix, and the breaking change. It explains that keys containing "/" or "~" were registered and referenced unescaped, and that the workspace now registers components, channels, channel messages, and servers under escaped pointers. It also describes how the 2.x reader escapes reference keys and how names recovered from references are unescaped. It states the BREAKING CHANGE clearly. The template's "Changelog" section (Add/Remove entries) and "Related Issues" section (Closes #...) are missing, so the description only partly follows the template.
Resolution
Consider adding the "Changelog" section with an entry such as "Fix: local references to keys containing '/' or '~' now use RFC 6901 escaping" and the "Related Issues" section with a closing reference (for example, "Closes #<issue-number>") if an issue exists.
-
-
Finishing Touches: 💡 1
-
📝 Generate docstrings: 💡
-
- Commit to this branch
- Create a new PR
🧪 Generate unit tests (beta)
-
- Commit to this branch
- Create a new PR
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Comment @coderabbitai help to get the list of available commands.
|
@bielu this might make your channels PR partially obsolete. |
|
@VisualBean yep you made my pr redudant :) |
|
I see you point on the preencoded values, but will leave it for now. |
Keys containing "/" or "~" were registered and referenced unescaped, so a spec-correct pointer such as "#/channels/user~1signedup" missed the workspace and was resolved from the raw document into a separate copy of the channel. Unescaped pointers only resolved because both sides skipped escaping.
The workspace now registers every component, channel, channel message and server under its escaped pointer, and the 2.x reader escapes the keys of every reference it builds. Names recovered from references (2.x message keys, 2.x channel servers and security requirement names) are taken from the parsed pointer, so they come back unescaped. This keeps 2.x and 3.x reading, writing, upgrading and downgrading intact for such keys.
BREAKING CHANGE: a local reference to a key containing "/" or "~" must escape it as "~1" or "~0" (RFC 6901). The unescaped form no longer resolves.
Summary by CodeRabbit
/or~, improving reference resolution and document round-tripping.