feat: Clean up A2ACardResolver (#28)

* feat: Clean up A2ACardResolver

- Support using a shared HttpClient
- Implement GetAgentCard with synchronous APIs on .NET Core
- Avoid response buffering
- Use HttpStatusCode enum rather than int
- Specify ConfigureAwait
- Avoid unnecessary null checks on _logger

* Address feedback

Author: stephentoub

src/A2A/Client/A2ACardResolver.cs

@@ -1,5 +1,7 @@
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Logging.Abstractions;
+using System.Diagnostics;
+using System.Net;
 using System.Text.Json;
 
 namespace A2A;
@@ -9,30 +11,34 @@ namespace A2A;
 /// </summary>
 public sealed class A2ACardResolver
 {
+    private readonly HttpClient _httpClient;
+    private readonly Uri _agentCardPath;
+    private readonly ILogger _logger;
+
     /// <summary>
     /// Creates a new instance of the A2ACardResolver
     /// </summary>
-    /// <param name="httpClient">Optional HTTP client (if not provided, a new one will be created)</param>
-    /// <param name="agentCardPath">Path to the agent card (defaults to /.well-known/agent.json)</param>
+    /// <param name="httpClient">Optional HTTP client (if not provided, a shared one will be used)</param>
+    /// <param name="agentCardPath">Path to the agent card (defaults to "/.well-known/agent.json")</param>
     /// <param name="logger">Optional logger</param>
     public A2ACardResolver(
-        HttpClient httpClient,
+        HttpClient? httpClient,
         string agentCardPath = "/.well-known/agent.json",
         ILogger? logger = null)
     {
-        _agentCardPath = agentCardPath.TrimStart('/');
-        _httpClient = httpClient;
-        _httpClient.Timeout = TimeSpan.FromSeconds(30); // Set a reasonable timeout
+        if (agentCardPath is null)
+        {
+            throw new ArgumentNullException(nameof(agentCardPath), "Agent card path cannot be null.");
+        }
+
+        _httpClient = httpClient ?? A2AClient.s_sharedClient;
+        _agentCardPath = new Uri(agentCardPath.TrimStart('/'), UriKind.RelativeOrAbsolute);
         _logger = logger ?? NullLogger.Instance;
-    }
 
-    /// <summary>
-    /// Gets the agent card synchronously
-    /// </summary>
-    /// <returns>The agent card</returns>
-    public AgentCard GetAgentCard()
-    {
-        return GetAgentCardAsync().GetAwaiter().GetResult();
+        if (_httpClient.BaseAddress is null && !_agentCardPath.IsAbsoluteUri)
+        {
+            throw new ArgumentException($"HttpClient.BaseAddress must be set when using a relative {nameof(agentCardPath)}.", nameof(httpClient));
+        }
     }
 
     /// <summary>
@@ -42,44 +48,44 @@ public AgentCard GetAgentCard()
     /// <returns>The agent card</returns>
     public async Task<AgentCard> GetAgentCardAsync(CancellationToken cancellationToken = default)
     {
-        string url = $"{_httpClient.BaseAddress}/{_agentCardPath}";
-        _logger?.LogInformation("Fetching agent card from {Url}", url);
+        if (_logger.IsEnabled(LogLevel.Information))
+        {
+            Debug.Assert(_agentCardPath.IsAbsoluteUri || _httpClient.BaseAddress is not null);
+            _logger.LogInformation("Fetching agent card from '{Url}'", _agentCardPath.IsAbsoluteUri ?
+                _agentCardPath :
+                new Uri(_httpClient.BaseAddress!, _agentCardPath.ToString()));
+        }
 
         try
         {
-            var response = await _httpClient.GetAsync(_agentCardPath, cancellationToken);
+            using var response = await _httpClient.GetAsync(_agentCardPath, HttpCompletionOption.ResponseHeadersRead, cancellationToken).ConfigureAwait(false);
 
             response.EnsureSuccessStatusCode();
 
-            var content = await response.Content.ReadAsStreamAsync(
-#if NET8_0_OR_GREATER
+            using var responseStream = await response.Content.ReadAsStreamAsync(
+#if NET
                 cancellationToken
 #endif
-                );
+                ).ConfigureAwait(false);
 
-            return JsonSerializer.Deserialize(content, A2AJsonUtilities.JsonContext.Default.AgentCard) ??
+            return JsonSerializer.Deserialize(responseStream, A2AJsonUtilities.JsonContext.Default.AgentCard) ??
                 throw new A2AClientJsonException("Failed to parse agent card JSON.");
         }
         catch (JsonException ex)
         {
-            _logger?.LogError(ex, "Failed to parse agent card JSON");
+            _logger.LogError(ex, "Failed to parse agent card JSON");
             throw new A2AClientJsonException($"Failed to parse JSON: {ex.Message}");
         }
         catch (HttpRequestException ex)
         {
-#if NET8_0_OR_GREATER
-            int statusCode = (int)(ex.StatusCode ?? System.Net.HttpStatusCode.InternalServerError);
-#else
-            int statusCode = (int)System.Net.HttpStatusCode.InternalServerError;
+            HttpStatusCode statusCode =
+#if NET
+                ex.StatusCode ??
 #endif
-            _logger?.LogError(ex, "HTTP request failed with status code {StatusCode}", statusCode);
+                HttpStatusCode.InternalServerError;
+
+            _logger.LogError(ex, "HTTP request failed with status code {StatusCode}", statusCode);
             throw new A2AClientHTTPException(statusCode, ex.Message);
         }
     }
-
-    #region private
-    private readonly HttpClient _httpClient;
-    private readonly string _agentCardPath;
-    private readonly ILogger _logger;
-    #endregion
 }

src/A2A/Client/A2AClient.cs

@@ -7,7 +7,7 @@ namespace A2A;
 
 public sealed class A2AClient : IA2AClient
 {
-    private static readonly HttpClient s_sharedClient = new();
+    internal static readonly HttpClient s_sharedClient = new();
 
     private readonly HttpClient _httpClient;
 

src/A2A/JsonRpc/ErrorTypes.cs

@@ -1,4 +1,6 @@
-namespace A2A;
+using System.Net;
+
+namespace A2A;
 
 /// <summary>
 /// Base exception for A2A client errors
@@ -24,7 +26,7 @@ public class A2AClientHTTPException : A2AClientException
     /// <summary>
     /// The HTTP status code
     /// </summary>
-    public int StatusCode { get; }
+    public HttpStatusCode StatusCode { get; }
 
     /// <summary>
     /// The error message
@@ -36,8 +38,8 @@ public class A2AClientHTTPException : A2AClientException
     /// </summary>
     /// <param name="statusCode">The HTTP status code</param>
     /// <param name="message">The error message</param>
-    public A2AClientHTTPException(int statusCode, string message)
-        : base($"HTTP Error {statusCode}: {message}")
+    public A2AClientHTTPException(HttpStatusCode statusCode, string message)
+        : base($"HTTP Error {(int)statusCode}: {message}")
     {
         StatusCode = statusCode;
         ErrorMessage = message;

tests/A2A.UnitTests/JsonRpc/ErrorTypesTests.cs

@@ -1,4 +1,6 @@
-namespace A2A.UnitTests.JsonRpc;
+using System.Net;
+
+namespace A2A.UnitTests.JsonRpc;
 
 public class ErrorTypesTests
 {
@@ -20,10 +22,10 @@ public void A2AClientError_ConstructsWithMessageAndInnerException()
     public void A2AClientHTTPError_PropertiesSetCorrectly()
     {
         // Act
-        var sut = new A2AClientHTTPException(404, "Not Found");
+        var sut = new A2AClientHTTPException(HttpStatusCode.NotFound, "Not Found");
 
         // Assert
-        Assert.Equal(404, sut.StatusCode);
+        Assert.Equal(HttpStatusCode.NotFound, sut.StatusCode);
         Assert.Equal("Not Found", sut.ErrorMessage);
         Assert.Contains("404", sut.Message);
         Assert.Contains("Not Found", sut.Message);