Package org.a2aproject.sdk.client.http

Class JdkA2AHttpClient

java.lang.Object
org.a2aproject.sdk.client.http.JdkA2AHttpClient
All Implemented Interfaces:
A2AHttpClient
public class JdkA2AHttpClient extends Object implements A2AHttpClient
Default HTTP client implementation using JDK 11+ HttpClient.

This is the fallback implementation used when no higher-priority A2AHttpClientProvider is available. It provides full support for:

  • HTTP/2 with automatic fallback to HTTP/1.1
  • Synchronous GET, POST, and DELETE requests
  • Asynchronous Server-Sent Events (SSE) streaming

Security Note: GET, DELETE, and GET SSE requests always use an internal no-redirect client to prevent credential leakage, regardless of the redirect policy configured on the supplied HttpClient. POST requests do not follow HTTP redirects automatically either. To enable one-hop redirect following for a POST request, call followRedirects(true) on the builder. Redirect headers are filtered by RedirectHeaderPolicy.

Host header limitation: the underlying JDK HttpClient rejects addHeader("Host", ...) with an IllegalArgumentException ("restricted header name") unless the JVM is started with -Djdk.httpclient.allowRestrictedHeaders=host. This is a JDK-wide restriction that cannot be worked around per-client-instance. Applications that need to send an explicit Host header (for example, connecting directly to an instance while presenting the hostname a load balancer normally supplies) should either set that system property or use an A2AHttpClient implementation that does not build on java.net.http.HttpClient, such as org.a2aproject.sdk.client.http.vertx.VertxA2AHttpClient (the a2a-java-sdk-http-client-vertx extra), which has no such restriction.

Provider Priority: 0 (lowest - used as fallback)

This implementation is registered via JdkA2AHttpClientProvider in the ServiceLoader system and is automatically used by A2AHttpClientFactory when no other provider is available.

See Also:

  • Constructor Details

    • JdkA2AHttpClient

      public JdkA2AHttpClient()
      Creates a new JDK-based HTTP client with secure defaults.

      Configures the client with:

      • HTTP/2 preferred (with HTTP/1.1 fallback)
      • No automatic redirect following (security hardening to prevent credential leakage)

      To enable redirect following for POST requests, call followRedirects(true) on each builder.

    • JdkA2AHttpClient

      public JdkA2AHttpClient(HttpClient httpClient)
      Creates a new JDK-based HTTP client using a caller-provided JDK HttpClient.

      This constructor allows full control over the HttpClient configuration, such as custom SSL settings, proxy, or executor. GET, DELETE, and GET SSE requests always route through an internal no-redirect clone of the supplied client, so their redirect policy is enforced by the SDK regardless of the policy set on the supplied HttpClient.

      For POST redirect following, the supplied client must use HttpClient.Redirect.NEVER; the SDK applies its redirect header policy before issuing the follow-up request.

      POST redirect opt-in requires two steps: this client is only used for a POST request when followRedirects(true) is also called on the builder. If the flag is not set the builder uses an internal no-redirect client regardless of the policy configured on the httpClient supplied here.

      Parameters:
      httpClient - the JDK HTTP client to delegate requests to
      Throws:
      IllegalArgumentException - if httpClient is null

    • JdkA2AHttpClient

      public JdkA2AHttpClient(HttpClient httpClient, SSEParserConfig sseParserConfig)
      Creates a new JDK-based HTTP client using a caller-provided JDK HttpClient and custom SSE parser limits.
      Parameters:
      httpClient - the JDK HTTP client to delegate requests to
      sseParserConfig - the SSE parser configuration to use for streaming responses
      Throws:
      IllegalArgumentException - if httpClient or sseParserConfig is null

    • JdkA2AHttpClient

      public JdkA2AHttpClient(HttpClient httpClient, SSEParserConfig sseParserConfig, RedirectHeaderPolicy redirectHeaderPolicy)
      Creates a new JDK HTTP client with caller-supplied transport and redirect policies.

      When followRedirects(true) is used, the supplied httpClient must be configured with HttpClient.Redirect.NEVER. This lets the SDK apply the redirect header policy before issuing the follow-up request.

      Parameters:
      httpClient - the JDK HTTP client to delegate requests to
      sseParserConfig - the SSE parser configuration
      redirectHeaderPolicy - policy applied to explicitly enabled POST redirects

  • Method Details

    • withRedirectHeaderPolicy

      public static JdkA2AHttpClient withRedirectHeaderPolicy(RedirectHeaderPolicy redirectHeaderPolicy)
      Creates a new JDK HTTP client with a custom redirect header policy.
      Parameters:
      redirectHeaderPolicy - policy applied to explicitly enabled POST redirects
      Returns:
      a client with secure transport defaults and the supplied redirect policy

    • withRedirectHeaderPolicy

      public static JdkA2AHttpClient withRedirectHeaderPolicy(HttpClient httpClient, RedirectHeaderPolicy redirectHeaderPolicy)
      Creates a JDK HTTP client with a caller-supplied transport and redirect header policy.
      Parameters:
      httpClient - the JDK HTTP client to delegate requests to
      redirectHeaderPolicy - policy applied to explicitly enabled POST redirects
      Returns:
      a client using the supplied transport and redirect policy

    • withSseConfig

      public static JdkA2AHttpClient withSseConfig(SSEParserConfig sseParserConfig)
      Creates a new JDK-based HTTP client with secure defaults and custom SSE parser limits.

      Named factory method avoids overload ambiguity with JdkA2AHttpClient(HttpClient).

      Parameters:
      sseParserConfig - the SSE parser configuration to use for streaming responses
      Returns:
      a new JdkA2AHttpClient with the given SSE parser configuration
      Throws:
      IllegalArgumentException - if sseParserConfig is null

    • withConfiguration

      public static JdkA2AHttpClient withConfiguration(SSEParserConfig sseParserConfig, RedirectHeaderPolicy redirectHeaderPolicy)
      Creates a default JDK client with custom SSE and redirect settings.

    • createGet

      public A2AHttpClient.GetBuilder createGet()
      Description copied from interface: A2AHttpClient
      Creates a builder for GET requests.
      Specified by:
      createGet in interface A2AHttpClient
      Returns:
      a new GetBuilder instance

    • createPost

      public A2AHttpClient.PostBuilder createPost()
      Description copied from interface: A2AHttpClient
      Creates a builder for POST requests.
      Specified by:
      createPost in interface A2AHttpClient
      Returns:
      a new PostBuilder instance

    • createDelete

      public A2AHttpClient.DeleteBuilder createDelete()
      Description copied from interface: A2AHttpClient
      Creates a builder for DELETE requests.
      Specified by:
      createDelete in interface A2AHttpClient
      Returns:
      a new DeleteBuilder instance