Merge remote-tracking branch 'origin/main' into refactor/error-handling-unification

# Conflicts:
#	README.md

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,7 +247,7 @@ 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`). |
+| `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`. |
@@ -255,16 +256,19 @@ See [docs/pipelines.md](docs/pipelines.md) for the step-author walkthrough.
 | `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`

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

@@ -372,8 +372,8 @@ defaults (per Square: `FAIL_ON_UNKNOWN_PROPERTIES=false`, `WRITE_DATES_AS_TIMEST
 
 ### WU-9: Pagination primitives
 
-**Status: shipped.** `Page`, `Paginator`, `PaginationStrategy`, and the four strategies
-(`Cursor` / `PageNumber` / `LinkHeader` / `Token`) are in `sdk-core/.../pagination`, alongside
+**Status: shipped.** `Page`, `Paginator`, `PaginationStrategy`, and the three strategies
+(`Cursor` / `PageNumber` / `LinkHeader`) are in `sdk-core/.../pagination`, alongside
 helper types `SimplePage` and `RequestRebuilder`. `Paginator` gained a `maxPages` safety cap
 (default `Long.MAX_VALUE`) beyond the original sketch, to bound runaway iteration against servers
 that never advance their cursor.
@@ -390,7 +390,6 @@ link-header strategies without over-engineering. Sync first; async adapter follo
   - `CursorPaginationStrategy<T>(cursorPath, itemsPath, parser)` — read `next_cursor` from body
   - `PageNumberPaginationStrategy<T>(pageParam, itemsPath, parser)` — increment page number
   - `LinkHeaderPaginationStrategy<T>(itemsPath, parser)` — RFC 5988 `Link: <url>; rel="next"`
-  - `TokenPaginationStrategy<T>(tokenPath, tokenParam, itemsPath, parser)` — token in body, sent as query param
 - `sdk-core/src/main/kotlin/org/dexpace/sdk/core/pagination/PaginatorTests.kt` (test) — table-driven tests against MockWebServer fixtures.
 
 **Acceptance criteria:**