merge: bring main into feat/evict-bearer-on-401

Resolve a conflict in BearerTokenAuthStepTest.kt: keep the IoProvider
@BeforeTest setup added for the 401-challenge retry path, and adopt
main's section comment.

Author: OmarAlJarrah

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+# Run the full Gradle build on every pull request and on pushes to main.
+# `./gradlew build` runs the complete quality gate: tests, ktlint, detekt,
+# apiCheck (binary-compatibility), explicit-API strict mode, allWarningsAsErrors,
+# and the aggregate 80% Kover line-coverage floor.
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+# Cancel superseded runs on the same ref so only the latest commit of a branch/PR builds.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          # The styleguide directory is a git submodule; fetch it so the working tree matches local checkouts.
+          submodules: recursive
+
+      # Install a single Temurin JDK 21. The build's Gradle daemon runs on this JVM, and the
+      # foojay-resolver-convention plugin (settings.gradle.kts) auto-provisions the JDK 8 and
+      # JDK 11 toolchains the Java-8 and JDK-11 modules require. JDK 21 also satisfies the
+      # virtual-threads module's toolchain. JDK 21 (rather than the newest LTS) is deliberate:
+      # detekt 1.23.x crashes on JDK 25+, so keeping the daemon on 21 keeps the detekt gate green.
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+
+      # Built-in Gradle dependency and build caching, plus wrapper validation.
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Build
+        run: ./gradlew build

AUDIT.md

@@ -7,6 +7,7 @@
 
 <h1 align="center">Java SDKs Platform</h1>
 
+[![CI](https://github.com/dexpace/java-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/dexpace/java-sdk/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Kotlin](https://img.shields.io/badge/kotlin-2.3.21-7F52FF.svg?logo=kotlin&logoColor=white)](https://kotlinlang.org)
 ![JDK](https://img.shields.io/badge/JDK-8%2B-437291.svg?logo=openjdk&logoColor=white)
@@ -246,25 +247,28 @@ See [docs/pipelines.md](docs/pipelines.md) for the step-author walkthrough.
 |---|---|
 | `client` | `HttpClient`, `AsyncHttpClient` — the two transport SPIs (sync and async). |
 | `http.request` | `Request`, `RequestBody`, `FileRequestBody`, `LoggableRequestBody`, `Method`. |
-| `http.response` | `Response`, `ResponseBody`, `LoggableResponseBody`, `Status` (a value-carrying class with a total `fromCode`), `HttpResponseException`. |
-| `http.response.exception` | Typed `HttpException` hierarchy (`BadRequestException`, `RequestTimeoutException`, `TooManyRequestsException`, `ServiceUnavailableException`, …) with `retryable` derived from `RetryUtils.isRetryable`, plus `NetworkException` and `HttpExceptionFactory`. |
+| `http.response` | `Response`, `ResponseBody`, `LoggableResponseBody`, `Status` (a value-carrying class with a total `fromCode`), plus the raw-vs-parsed seam: `ResponseHandler<T>` (with dep-free `string()`/`empty()` handlers) and a lazy, parse-once `ParsedResponse<T>`. |
+| `http.response.exception` | Typed `HttpException` hierarchy (`BadRequestException`, `RequestTimeoutException`, `TooManyRequestsException`, `ServiceUnavailableException`, …) with `isRetryable` derived from `RetryUtils.isRetryable` and exposed via the `Retryable` interface, plus `NetworkException` and `HttpExceptionFactory`. |
 | `http.common` | `Headers`, `HttpHeaderName` (interned), `MediaType`, `Protocol`, `HttpRange`, `ETag`, `RequestConditions`. |
 | `http.context` | `CallContext` → `DispatchContext` → `RequestContext` → `ExchangeContext` chain, `ContextStore`. |
 | `http.pipeline` | Sync (`HttpStep` / `HttpPipeline` / `HttpPipelineBuilder` / `PipelineNext` / `Stage`) and async (`AsyncHttpStep` / `AsyncHttpPipeline` / `AsyncHttpPipelineBuilder` / `AsyncPipelineNext`) pipeline machinery, plus `AsyncPipelineBridges`. |
 | `http.pipeline.steps` | Concrete steps: `RetryStep`, `RedirectStep`, `AuthStep`, `KeyCredentialAuthStep`, `BearerTokenAuthStep`, `InstrumentationStep`, `SetDateStep`, and their `*Options` / `*Condition` types. |
 | `http.auth` | `Credential` sealed hierarchy (`KeyCredential`, `NamedKeyCredential`, `BearerToken`), `BearerTokenProvider`, `AuthScheme`, `AuthMetadata`, RFC 7235 challenge parser, `BasicChallengeHandler`, `DigestChallengeHandler`, `CompositeChallengeHandler`. |
 | `http.sse` | `ServerSentEventReader` (WHATWG spec), `ServerSentEvent`, `ServerSentEventListener`, `BufferedSource.readServerSentEvents()`. |
 | `http.paging` | `PagedIterable<T>`, `PagedResponse<T>`, `PagingOptions` with `byPage()` and `stream()` accessors. |
-| `pagination` | `Paginator<T>` (with a `maxPages` safety cap) over cursor / page-number / token / link-header `PaginationStrategy` implementations, plus `Page<T>` / `SimplePage<T>`. |
+| `pagination` | `Paginator<T>` (with a `maxPages` safety cap) over cursor / page-number / link-header `PaginationStrategy` implementations, plus `Page<T>` / `SimplePage<T>`. Token-style APIs use `CursorPaginationStrategy` with the query-param name set (e.g. `"page_token"`). |
 | `pipeline` | Recovery-aware primitives: `RequestPipeline`, `ResponsePipeline`, `ExecutionPipeline` over a sealed `ResponseOutcome`, with steps (`pipeline.step`, `pipeline.step.retry`) like `RetryStep`, `ResponseRecoveryStep`, `IdempotencyKeyStep`, `ClientIdentityStep`. |
-| `serde` | `Serde`, `Serializer`, `Deserializer` abstractions and `Tristate<T>` (absent / null / present). |
+| `serde` | `Serde`, `Serializer`, `Deserializer` abstractions, `Tristate<T>` (absent / null / present), and `SerdeException` (the unchecked failure adapters translate codec errors into). |
 | `io` | `Source`, `Sink`, `Buffer`, `BufferedSource`, `BufferedSink`, `IoProvider`, `Io`, `TeeSink`. |
 | `instrumentation` | `ClientLogger` (zero-alloc disabled path), `LoggingEvent`, `UrlRedactor`, `Tracer` / `NoopTracer`, `Span` / `NoopSpan`, `InstrumentationContext`. |
 | `instrumentation.metrics` | `Meter`, `LongCounter`, `DoubleHistogram`, `NoopMeter`. |
 | `config` | `Configuration` (system-property + env-var layered lookup), `ConfigurationBuilder`. |
 | `util` | `Clock`, `Uuids` (non-blocking v4), `DateTimeRfc1123`, `RetryUtils`, `ProxyOptions`, `Futures`. |
 | `generics` | `Builder<T>` — the generic builder interface every SDK builder implements. |
 
+Token-style APIs (`next_page_token`, `pageToken`, …) are served by `CursorPaginationStrategy`:
+construct it with the desired query-param name, e.g. `CursorPaginationStrategy(items, extractor, "page_token")`.
+
 ## Building
 
 ```bash

README.md

@@ -271,6 +271,10 @@ Shipped pillar/step implementations live in `http.pipeline.steps`: `DefaultRedir
 `DefaultRetryStep`, `AuthStep` (+ `BearerTokenAuthStep` / `KeyCredentialAuthStep`),
 `DefaultInstrumentationStep`, and the redirect/retry option types.
 
+For why this layer uses ordered stages with pillar-uniqueness rather than nested `HttpClient`
+decorators — and the one cost that buys (the `next.copy()` re-drive contract) — see
+[Pipeline Mechanism](pipelines.md#why-ordered-stages-not-nested-decorators).
+
 #### Recovery-aware primitives (`org.dexpace.sdk.core.pipeline`)
 
 A lower-level layer that threads a sealed `ResponseOutcome` so recovery steps observe and
@@ -346,9 +350,12 @@ Two complementary surfaces for walking multi-page responses.
 |-----------------------------------------------------------------|-----------------------------------------------------------------------|
 | `Paginator<T>`                                                  | Lazily iterates pages by re-issuing requests through an `HttpClient`; carries a `maxPages` safety cap |
 | `PaginationStrategy<T>`                                         | Computes the next-page request (or stops) from the current page       |
-| `CursorPaginationStrategy` / `PageNumberPaginationStrategy` / `TokenPaginationStrategy` / `LinkHeaderPaginationStrategy` | The four shipped strategies |
+| `CursorPaginationStrategy` / `PageNumberPaginationStrategy` / `LinkHeaderPaginationStrategy` | The shipped strategies |
 | `PagedIterable<T>`                                              | First/next-page fetcher abstraction over `PagedResponse`, with its own `maxPages` cap |
 
+Token-style APIs (`next_page_token`, `pageToken`, …) are handled by `CursorPaginationStrategy`
+constructed with the query-param name set (e.g. `"page_token"`), so no separate token strategy is needed.
+
 ### Serialization
 
 **Package**: `org.dexpace.sdk.core.serde`
@@ -575,8 +582,8 @@ responds in a uniform way:
    subsequent blocking call also surfaces it.
 3. Throws `InterruptedIOException` (or the operation's natural failure exception with
    `InterruptedException` added as a suppressed cause).
-4. Classifies the interruption as **non-retryable** — `HttpResponseException.isRetryable`
-   returns `false` for an interrupt-driven failure.
+4. Classifies the interruption as **non-retryable** — an interrupt-driven failure is not a
+   `Retryable` condition, so the retry step never re-issues it.
 
 Loops bounded by user input (retry attempts, paged iteration, server-sent-event
 consumption, drain loops in body logging) check `Thread.currentThread().isInterrupted` at
@@ -653,8 +660,8 @@ they should construct a fresh one.
 |----------------------|-------------------------------------------------------------------------------------------------|
 | `io`                 | Source, Sink, BufferedSource, BufferedSink, Buffer, IoProvider, Io, TeeSink (internal)          |
 | `http.request`       | Request, RequestBody, FileRequestBody, LoggableRequestBody, Method                              |
-| `http.response`      | Response, ResponseBody, LoggableResponseBody, Status, HttpResponseException                     |
-| `http.response.exception` | HttpException, HttpExceptionFactory, RequestTimeoutException (and siblings), NetworkException |
+| `http.response`      | Response, ResponseBody, LoggableResponseBody, Status                                            |
+| `http.response.exception` | HttpException, HttpExceptionFactory, Retryable, RequestTimeoutException (and siblings), NetworkException |
 | `http.common`        | Headers, MediaType, CommonMediaTypes, Protocol, ETag, HttpRange, RequestConditions             |
 | `http.auth`          | Credential, KeyCredential, BearerToken, ChallengeHandler, Basic/Digest/CompositeChallengeHandler, AuthChallengeParser |
 | `http.context`       | CallContext, DispatchContext, RequestContext, ExchangeContext, ContextStore                     |

docs/architecture.md

@@ -14,6 +14,7 @@ and the concurrency decisions behind them.
     - [Architecture](#architecture)
     - [LoggableRequestBody — Tee-Write Strategy](#loggablerequestbody--tee-write-strategy)
     - [LoggableResponseBody — Drain-Once Strategy](#loggableresponsebody--drain-once-strategy)
+    - [Logged body size vs. the body the consumer receives](#logged-body-size-vs-the-body-the-consumer-receives)
     - [Reading a Snapshot](#reading-a-snapshot)
 - [Internal Stream Utilities](#internal-stream-utilities)
 - [Concurrency Design](#concurrency-design)
@@ -240,6 +241,45 @@ retains whatever bytes were read before the failure and caches the exception:
   post-mortem logging that records "what we got" alongside the exception.
 - `captureException` surfaces the cached exception (or `null`) without triggering a drain.
 
+### Logged body size vs. the body the consumer receives
+
+When `HttpLogLevel.BODY_AND_HEADERS` is enabled, the instrumentation step
+(`DefaultInstrumentationStep` / `DefaultAsyncInstrumentationStep`) wraps the response body in a
+`LoggableResponseBody` bounded to `HttpInstrumentationOptions.bodyPreviewMaxBytes` (default
+8 KiB, `DEFAULT_BODY_PREVIEW_MAX_BYTES`). Two consequences follow that are easy to miss when
+reading the logs:
+
+**1. The body delivered downstream can be larger than the logged preview.** The cap bounds only
+the in-memory *capture*, not the body. For a response larger than `bodyPreviewMaxBytes`, the
+step buffers the preview prefix and the wrapper then streams the full body to the consumer — it
+replays the captured prefix and continues from the live tail (see the bounded-capture diagram
+above). The preview you see in the log is a prefix; the consumer still reads every byte.
+
+**2. The logged size fields measure different things.** The step emits two size-related fields
+on the `http.response` event, and they are not the same number for an over-cap body:
+
+| Field                     | Source                                       | What it reports                                                                 |
+|---------------------------|----------------------------------------------|---------------------------------------------------------------------------------|
+| `response.body.size`      | `loggableBody.snapshot(bodyPreviewMaxBytes)` | Size of the **captured preview** — bounded by `bodyPreviewMaxBytes`             |
+| `response.body.preview`   | the same captured bytes, decoded as UTF-8    | The preview text (a prefix for an over-cap body)                                |
+| `response.content.length` | `response.body.contentLength()`              | The body's **true** length when the origin declared one (`Content-Length`); `-1` for unknown-length / streaming bodies |
+
+So `response.body.size` is the *captured/preview* size, **not** necessarily the full body size.
+When a body exceeds the cap, `response.body.size` saturates near `bodyPreviewMaxBytes` while
+`response.content.length` still shows the real length. Read `content.length` (not
+`body.size`) when you need the full size, and treat `body.preview` as a prefix that may be
+truncated. The two agree only when the whole body fit within the cap — exactly the case where
+`contentLength()` itself returns the captured size (see **`contentLength()`** above).
+
+**Streaming / unknown-length bodies (async path).** `DefaultAsyncInstrumentationStep` skips the
+capture entirely when `contentLength() < 0`, because the bounded drain would run on the
+future-completion thread and a slow producer could stall it. Such bodies stream to the consumer
+unwrapped, so they carry **no** `response.body.size` / `response.body.preview` fields at all —
+absence of those fields is expected for chunked or streaming responses, not a logging bug. The
+synchronous `DefaultInstrumentationStep` drains known-length and unknown-length bodies alike (it
+runs on the caller's thread), but the size-vs-preview distinction above applies to it just the
+same.
+
 ### Reading a Snapshot
 
 The only logging output is a raw `ByteArray`:

docs/http-body-logging-and-concurrency.md

@@ -286,8 +286,9 @@ on whether a code is one the SDK recognizes.
 The SDK ships a typed exception hierarchy under `org.dexpace.sdk.core.http.response.exception`.
 The shape mirrors `gax`'s `ApiException` taxonomy translated to HTTP terms: one base class plus
 one concrete subclass per canonical status code. The base class derives its retryable flag
-from a single source of truth, so a downstream retry policy can read `exception.retryable`
-instead of maintaining a parallel predicate map.
+from a single source of truth and exposes it through the `Retryable` interface, so a downstream
+retry policy can read `(t as? Retryable)?.isRetryable` instead of maintaining a parallel
+predicate map or matching concrete exception types.
 
 ### HttpException Hierarchy
 
@@ -302,16 +303,21 @@ abstract class HttpException(
     val body: ResponseBody?,         // lazy — NOT eagerly buffered
     message: String? = null,
     cause: Throwable? = null,
-) : RuntimeException(message, cause) {
-    val retryable: Boolean = RetryUtils.isRetryable(status.code)
+    val value: Any? = null,          // slot for a deserialized error payload (generated layer)
+) : RuntimeException(message, cause), Retryable {
+    override val isRetryable: Boolean = RetryUtils.isRetryable(status.code)
     fun bodySnapshot(maxBytes: Int = DEFAULT_SNAPSHOT_BYTES): ByteArray?
 }
 ```
 
-`retryable` is a `val` **derived** at construction from `RetryUtils.isRetryable(status.code)`,
+`isRetryable` is a `val` **derived** at construction from `RetryUtils.isRetryable(status.code)`,
 not hardcoded per subclass and not a constructor parameter. This guarantees the baked flag
 can never disagree with the live retry policy: 408 / 429 and the 5xx range except 501 and 505
-are retryable, everything else is not.
+are retryable, everything else is not. It satisfies the `Retryable` interface (shared with
+`NetworkException`), which is what the retry step keys off.
+
+`value` is a slot for a deserialized error payload, left `null` here — `sdk-core` does not
+parse bodies. The generated service layer populates it on a per-operation typed subclass.
 
 `bodySnapshot()` returns a non-consuming preview of the body bytes — it reads from a fresh
 `source().peek()` view so the primary read path is undisturbed — capped at `maxBytes`
@@ -355,19 +361,21 @@ subclass: it extends `java.io.IOException` so existing `catch (IOException)` cal
 working, and it carries no status/headers/body because none arrived.
 
 ```kotlin
-open class NetworkException(message: String? = null, cause: Throwable? = null) : IOException(message, cause) {
-    val retryable: Boolean = true  // always retryable at the SDK level
+open class NetworkException(message: String? = null, cause: Throwable? = null) :
+    IOException(message, cause), Retryable {
+    override val isRetryable: Boolean = true  // always retryable at the SDK level
 }
 ```
 
-The `retryable` flag is always `true`: nothing reached the server, so the SDK can safely
+The `isRetryable` flag is always `true`: nothing reached the server, so the SDK can safely
 attempt the request again. Whether the request itself is *safe* to retry (HTTP method
 idempotency, replayable body) is the retry policy's call, not this class's.
 
 ### HttpExceptionFactory
 
-`HttpExceptionFactory.fromResponse(response)` maps a non-2xx `Response` to the right
-subclass:
+`HttpExceptionFactory.fromResponse(response)` maps a 4xx/5xx `Response` to the right subclass.
+It is the one seam that turns an error response into a typed exception, so the family is
+produced consistently rather than re-derived at each call site:
 
 ```kotlin
 val response = httpClient.execute(request)
@@ -379,6 +387,14 @@ if (!response.status.isSuccess) {
 The factory throws `IllegalArgumentException` if called with a status outside 400..599 —
 1xx/2xx/3xx outcomes are not exceptions and should not be funneled through this path.
 
+For the recovery-aware pipeline, `ThrowOnHttpErrorStep` packages this mapping as a
+`ResponsePipelineStep`: drop it into a `ResponsePipeline.responseSteps` list and it calls
+`fromResponse` on a 4xx/5xx response and throws the result. `ResponsePipeline` converts that
+throw into a `ResponseOutcome.Failure`, which then flows through the recovery chain (e.g.
+`RetryStep`) exactly like a transport failure — and because the thrown `HttpException` is
+`Retryable`, retry classification keys off it uniformly. The step is a building block; no
+default pipeline in `sdk-core` assembles it for you.
+
 ---
 
 ## Common Types