Add symphony-bdk-http-jdk: a java.net.http.HttpClient-based ApiClient transport

docs/getting-started.md

@@ -24,6 +24,11 @@ yo @finos/symphony
 ## Creating your project _from scratch_
 This section will help you to understand how to create your bot application from scratch.
 
+> :warning: The default HTTP client dependency below, `symphony-bdk-http-jdk`, is currently `@API(EXPERIMENTAL)`. It has
+> zero third-party HTTP dependencies (built directly on `java.net.http.HttpClient`), but if you need an `@API(STABLE)`-only
+> dependency tree, use `symphony-bdk-http-jersey` instead. See [Migration Guide](migration.md) for details on switching
+> between HTTP client implementations.
+
 ### Maven-based project
 If you want to use [Maven](https://maven.apache.org/) as build system, you have to configure your root `pom.xml` as such:
 ```xml
@@ -59,7 +64,7 @@ If you want to use [Maven](https://maven.apache.org/) as build system, you have
         </dependency>
         <dependency>
             <groupId>org.finos.symphony.bdk</groupId>
-            <artifactId>symphony-bdk-http-jersey</artifactId> <!-- or symphony-bdk-http-webclient -->
+            <artifactId>symphony-bdk-http-jdk</artifactId> <!-- or symphony-bdk-http-jersey / symphony-bdk-http-webclient -->
             <scope>runtime</scope>
         </dependency>
         <dependency>
@@ -101,7 +106,7 @@ dependencies {
 
     // define dependencies without versions
     implementation 'org.finos.symphony.bdk:symphony-bdk-core'
-    runtimeOnly 'org.finos.symphony.bdk:symphony-bdk-http-jersey'           //  or symphony-bdk-http-webclient
+    runtimeOnly 'org.finos.symphony.bdk:symphony-bdk-http-jdk'              //  or symphony-bdk-http-jersey / symphony-bdk-http-webclient
     runtimeOnly 'org.finos.symphony.bdk:symphony-bdk-template-freemarker'    // or symphony-bdk-http-handlebars
 
     // logger configuration

docs/migration-4.x.md

@@ -167,6 +167,36 @@ No other generated class changes shape, method signatures, `equals`/`hashCode`/`
 consumer-visible way. Fluent builder method names (`addXxxItem`, `putXxxItem`, etc.) and all constructors are
 unchanged.
 
+## 9. New default HTTP client module: `symphony-bdk-http-jdk`
+
+BDK 4.x introduces `symphony-bdk-http-jdk`, a third `ApiClient` implementation built directly on
+`java.net.http.HttpClient` (available since Java 11, and part of the JDK itself), with **no third-party HTTP
+dependency**. It is now the module `docs/getting-started.md` and `docs/tech/architecture.md` present as the default
+for `symphony-bdk-core`, ahead of `symphony-bdk-http-jersey`.
+
+This is **not a required migration**. `symphony-bdk-http-jersey` keeps shipping and working exactly as before —
+existing consumers with an explicit `symphony-bdk-http-jersey` runtime dependency see no functional change, beyond
+its classes now being annotated `@API(status = API.Status.DEPRECATED)` (a documentation/IDE-warning signal only,
+not a removal notice).
+
+If you want to switch, replace your `symphony-bdk-http-jersey` (or `symphony-bdk-http-webclient`) runtime dependency
+with `symphony-bdk-http-jdk` — `ServiceLoader` picks up the new module's `ApiClientBuilderProvider` automatically, no
+code change to `SymphonyBdkBuilder` usage required. Before switching, be aware of two behavioral differences from
+`symphony-bdk-http-jersey`:
+
+- **Read timeout semantics.** `java.net.http.HttpClient` has no distinct socket/read timeout, only a connect timeout
+  and a per-request *total* timeout. `ApiClientBuilder#withReadTimeout` is mapped to the per-request total timeout —
+  the closest available approximation, but it bounds "the whole request took too long" rather than "no bytes arrived
+  for N ms". This can matter for large, legitimately slow responses (e.g. large file downloads) that previously
+  fit comfortably under a read-timeout-only budget.
+- **Filter support.** `java.net.http.HttpClient` has no request/response filter chain. `ApiClientBuilder#addFilter`
+  on `ApiClientBuilderJdk` only accepts a `Function<HttpRequest.Builder, HttpRequest.Builder>` (request mutation
+  only, e.g. adding a header) instead of an arbitrary Jersey `ClientRequestFilter`/`ClientResponseFilter`. Response-
+  inspecting filters cannot be ported to this module.
+
+`symphony-bdk-http-jdk` is currently `@API(status = API.Status.EXPERIMENTAL)`. If you need an `@API(STABLE)`-only
+dependency tree, stay on `symphony-bdk-http-jersey` for now.
+
 ## Support window
 
 BDK 3.x will receive critical security fixes for **6 months** following the BDK 4.0.0 release, where Symphony is

docs/tech/architecture.md

@@ -34,8 +34,9 @@ also provides a utility `com.symphony.bdk.http.api.HttpClient` class helping dev
 > :warning: It is important to notice that interface `com.symphony.bdk.http.api.ApiClient` is used by generated code.
 > Changing contract would break the build. See [Code Generation](#code-generation).
 
-At the moment, two different implementations have been created for the `com.symphony.bdk.http.api.ApiClient` interface:
-- `com.symphony.bdk.http.jersey2.ApiClientJersey2` contained in module `symphony-bdk-http-jersey` (default implementation for [Core](#symphony-bdk-core))
+At the moment, three different implementations have been created for the `com.symphony.bdk.http.api.ApiClient` interface:
+- `com.symphony.bdk.http.jdk.ApiClientJdk` contained in module `symphony-bdk-http-jdk` (default implementation for [Core](#symphony-bdk-core), built on `java.net.http.HttpClient` with no third-party HTTP dependency)
+- `com.symphony.bdk.http.jersey2.ApiClientJersey2` contained in module `symphony-bdk-http-jersey` (deprecated as [Core](#symphony-bdk-core)'s default in favor of `symphony-bdk-http-jdk`, but still supported)
 - `com.symphony.bdk.http.webclient.ApiClientWebClient` contained in module `symphony-bdk-http-webclient` (default implementation for [Spring Boot](#symphony-bdk-spring))
 
 ### symphony-bdk-template

openspec/changes/archive/2026-08-12-jdk-httpclient-transport/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-11