fix: escape 2.x channel server names in server references

The 2.x reader built "#/servers/{name}" without escaping the name, while the
writer decodes the pointer token. A literal name such as "a~1b" therefore
came back as "a/b" after a read/write round trip. The reader now escapes the
name, and the workspace registers document servers under the escaped pointer
so the reference still resolves. Server names this needs are outside the
spec's key pattern, so this only matters when validation is off.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: bielu

src/ByteBard.AsyncAPI.Readers/V2/AsyncApiChannelDeserializer.cs

@@ -21,7 +21,7 @@ internal static partial class AsyncApiV2Deserializer
         private static string GetServerReferenceKey(ValueNode valueNode)
         {
             var stringValue = valueNode.GetScalarValue();
-            return stringValue.StartsWith("#/servers/") ? stringValue : "#/servers/" + stringValue;
+            return stringValue.StartsWith("#/servers/") ? stringValue : "#/servers/" + JsonPointer.EscapeToken(stringValue);
         }
 
         private static readonly PatternFieldMap<AsyncApiChannel> ChannelPatternFields =

src/ByteBard.AsyncAPI/AsyncApiWorkspace.cs

@@ -219,7 +219,7 @@ public void RegisterComponents(AsyncApiDocument document)
                     registerableServerValue = this.ResolveReference<AsyncApiServer>(serverReference.Reference);
                 }
 
-                location = serverBaseUri + server.Key;
+                location = serverBaseUri + JsonPointer.EscapeToken(server.Key);
                 this.RegisterComponent(location, registerableServerValue);
             }
         }

src/ByteBard.AsyncAPI/JsonPointer.cs

@@ -83,12 +83,31 @@ public static JsonPointer FromUriFragment(string fragment)
             return new JsonPointer(Uri.UnescapeDataString(fragment));
         }
 
+        /// <summary>
+        /// Escapes a single reference token, so "~" becomes "~0" and "/" becomes "~1".
+        /// </summary>
+        /// <param name="token">The unescaped token.</param>
+        public static string EscapeToken(string token)
+        {
+            return token.Replace("~", "~0").Replace("/", "~1");
+        }
+
+        /// <summary>
+        /// Unescapes a single reference token, so "~1" becomes "/" and "~0" becomes "~".
+        /// Unlike parsing a pointer, this does not reject a "~" that is not part of an escape sequence.
+        /// </summary>
+        /// <param name="token">The escaped token.</param>
+        public static string UnescapeToken(string token)
+        {
+            return token.Replace("~1", "/").Replace("~0", "~");
+        }
+
         /// <summary>
         /// Gets the JSON string representation of this JSON pointer.
         /// </summary>
         public override string ToString()
         {
-            return string.Concat(this.Tokens.Select(token => "/" + token.Replace("~", "~0").Replace("/", "~1")));
+            return string.Concat(this.Tokens.Select(token => "/" + EscapeToken(token)));
         }
 
         private static string Unescape(string token, string pointer)

src/ByteBard.AsyncAPI/Models/AsyncApiChannel.cs

@@ -181,7 +181,7 @@ private static string GetV2ServerName(AsyncApiServerReference server)
             }
 
             // The 2.x reader keeps the name unescaped, while a 3.x pointer escapes it, so decode the whole remainder as one token.
-            return reference.FragmentId.Substring(serversPrefix.Length).Replace("~1", "/").Replace("~0", "~");
+            return JsonPointer.UnescapeToken(reference.FragmentId.Substring(serversPrefix.Length));
         }
     }
 }

test/ByteBard.AsyncAPI.Tests/Models/AsyncApiChannel_Should.cs

@@ -8,6 +8,7 @@
     using ByteBard.AsyncAPI.Models;
     using ByteBard.AsyncAPI.Models.Interfaces;
     using ByteBard.AsyncAPI.Readers;
+    using ByteBard.AsyncAPI.Validations;
     using NUnit.Framework;
 
     public class AsyncApiChannel_Should : TestBase
@@ -251,6 +252,68 @@ public void V3_AsyncApiChannel_WithServers_Reserializes()
             reserialized.Should().BePlatformAgnosticEquivalentTo(yaml);
         }
 
+        [TestCase("a~1b", "#/servers/a~01b")]
+        [TestCase("a/b", "#/servers/a~1b")]
+        public void V2_AsyncApiChannel_WithServerNameNeedingEscape_Reserializes(string serverName, string expectedReference)
+        {
+            var yaml =
+                $"""
+                asyncapi: 2.6.0
+                info:
+                  title: test spec
+                  version: 1.0.0
+                servers:
+                  {serverName}:
+                    url: example.com
+                    protocol: kafka
+                channels:
+                  mychannel:
+                    servers:
+                      - {serverName}
+                """;
+
+            var document = new AsyncApiStringReader(new AsyncApiReaderSettings { RuleSet = ValidationRuleSet.GetEmptyRuleSet() }).Read(yaml, out var diag);
+
+            diag.Errors.Should().BeEmpty();
+            var server = document.Channels.First().Value.Servers.Single();
+            server.Reference.Reference.Should().Be(expectedReference);
+            server.Host.Should().Be("example.com");
+
+            var reserialized = document.SerializeAsYaml(AsyncApiVersion.AsyncApi2_0);
+
+            reserialized.Should().BePlatformAgnosticEquivalentTo(yaml);
+        }
+
+        [Test]
+        public void V3_AsyncApiChannel_WithEscapedServerReference_ResolvesServer()
+        {
+            var yaml =
+                """
+                asyncapi: 3.1.0
+                info:
+                  title: test spec
+                  version: 1.0.0
+                servers:
+                  a/b:
+                    host: example.com
+                    protocol: kafka
+                channels:
+                  mychannel:
+                    servers:
+                      - $ref: '#/servers/a~1b'
+                components: { }
+                """;
+
+            var document = new AsyncApiStringReader(new AsyncApiReaderSettings { RuleSet = ValidationRuleSet.GetEmptyRuleSet() }).Read(yaml, out var diag);
+
+            diag.Errors.Should().BeEmpty();
+            document.Channels.First().Value.Servers.Single().Host.Should().Be("example.com");
+
+            var reserialized = document.SerializeAsYaml(AsyncApiVersion.AsyncApi3_0);
+
+            reserialized.Should().BePlatformAgnosticEquivalentTo(yaml);
+        }
+
         [Test]
         public void V3_AsyncApiChannel_WithServerReference_SerializesReference()
         {