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

@@ -49,12 +49,30 @@ public JsonPointer ParentPointer
             }
         }
 
+        /// <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 "~".
+        /// </summary>
+        /// <param name="token">The escaped token.</param>
+        public static string UnescapeToken(string token)
+        {
+            return token.Replace("~1", "/").Replace("~0", "~");
+        }
+
         /// <summary>
         /// Decode the string.
         /// </summary>
         private string Decode(string token)
         {
-            return Uri.UnescapeDataString(token).Replace("~1", "/").Replace("~0", "~");
+            return UnescapeToken(Uri.UnescapeDataString(token));
         }
 
         /// <summary>

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()
         {