refactor!: unify the HTTP error path on a single exception base and a Retryable interface

The response-carrying exception hierarchy had two overlapping bases and the
factory that produces the typed family was never wired into the error path.

- Collapse `HttpResponseException` (an `IOException` carrying a `Response` +
  optional error value) into `HttpException`. `HttpException` becomes the single
  response-carrying base; it gains an optional `value` slot for a deserialized
  error payload so the generated layer can stamp a typed body later. Transport
  failures keep using the `NetworkException` (`IOException`) sibling, so existing
  `catch (IOException)` sites for transport errors are unaffected.
- Introduce a `Retryable` interface (`val isRetryable: Boolean`) and implement it
  on both `HttpException` and `NetworkException`. The two types previously
  disagreed on the accessor name (`retryable` vs `isRetryable`); they now expose
  the same member through the interface. Retry classification in `RetryStep` keys
  off `Retryable` instead of matching concrete types, so a new retryable exception
  type participates automatically. The set of retryable statuses is unchanged
  (408/429 and 5xx except 501/505, still derived from `RetryUtils`).
- Wire `HttpExceptionFactory.fromResponse` into the live error path via a new
  `ThrowOnHttpErrorStep` response step: on a 4xx/5xx response it throws the
  factory's typed exception, which `ResponsePipeline` turns into a failure outcome
  that flows through the recovery chain (including retry) like a transport failure.
  Previously the factory had no callers and 4xx/5xx responses never produced the
  typed subclass family.

This is a binary-incompatible change to the public exception API: the
`HttpResponseException` type is removed, the `retryable` getter on `HttpException`
and `NetworkException` is renamed to `isRetryable`, and `HttpException` gains a
`value` property and a corresponding constructor parameter. API snapshot
regenerated; docs updated.

Author: OmarAlJarrah

README.md

@@ -246,8 +246,8 @@ 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`). |
+| `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`. |

docs/architecture.md

@@ -575,8 +575,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 +653,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/http.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,12 @@ 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.
 
+In the recovery-aware pipeline this is wired through `ThrowOnHttpErrorStep`, a
+`ResponsePipelineStep` that 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.
+
 ---
 
 ## Common Types

docs/pipelines.md

@@ -355,11 +355,13 @@ public class RetryStep(
 )
 ```
 
-It retries only when the outcome is a `Failure` whose throwable is classified retryable:
+It retries only when the outcome is a `Failure` whose throwable is classified retryable. The
+classifier keys off the `Retryable` interface, not concrete exception types:
 
-- An `HttpException` with `retryable == true` whose status code is in
+- An `HttpException` (which is `Retryable`) with `isRetryable == true` whose status code is in
   `RetrySettings.retryableStatuses`.
-- A `NetworkException` (a transport failure with no response on the wire — always retryable).
+- A `NetworkException` (also `Retryable`, always `true` — a transport failure with no response
+  on the wire).
 
 Idempotency is enforced independently of classification: a request is eligible only when its
 method is in `RetrySettings.retryableMethods` **or** its body is replayable. Non-idempotent

docs/refs-comparison.md

@@ -223,7 +223,7 @@ below records where each scheme's design was sourced from:
 **What shipped, and what's left:**
 
 1. `HttpException` is the base, with status-code-keyed subclasses (`NotFoundException`, `UnauthorizedException`, `TooManyRequestsException`, `InternalServerErrorException`, etc.) plus `ClientErrorException`/`ServerErrorException` fallbacks for unmapped 4xx/5xx. `NetworkException` is a sibling for transport failures. The set mirrors gax's taxonomy scaled to HTTP statuses.
-2. `retryable: Boolean` is a `val` derived once at construction from `RetryUtils.isRetryable(status.code)` — not a per-subclass constant. This is the single source of truth, so it can never disagree with the live retry policy (408 retryable; 501/505 not). A retry predicate is just `(t as? HttpException)?.retryable == true`.
+2. `isRetryable: Boolean` (from the `Retryable` interface) is a `val` derived once at construction from `RetryUtils.isRetryable(status.code)` — not a per-subclass constant. This is the single source of truth, so it can never disagree with the live retry policy (408 retryable; 501/505 not). `NetworkException` implements the same interface (always `true`), so a retry predicate keys off the interface: `(t as? Retryable)?.isRetryable == true`.
 3. The base exposes `status` + `headers` + a **lazy** `body: ResponseBody?` (not eagerly buffered), plus a non-consuming `bodySnapshot()` that reads from a `peek()` view so the primary read path is undisturbed — large 5xx bodies don't OOM. Per-operation per-status subclasses carrying typed bodies (Expedia pattern) are still codegen's job.
 4. Tolerant error-body parsing (Square's `SquareApiException.parseErrors`) remains future work — never throw inside an exception constructor; pass through the raw body on parse failure.
 

sdk-core/api/sdk-core.api

@@ -1100,16 +1100,6 @@ public final class org/dexpace/sdk/core/http/request/RequestBody$Companion {
 	public static synthetic fun create$default (Lorg/dexpace/sdk/core/http/request/RequestBody$Companion;[BLorg/dexpace/sdk/core/http/common/MediaType;ILjava/lang/Object;)Lorg/dexpace/sdk/core/http/request/RequestBody;
 }
 
-public class org/dexpace/sdk/core/http/response/HttpResponseException : java/io/IOException {
-	public fun <init> (Ljava/lang/String;Lorg/dexpace/sdk/core/http/response/Response;)V
-	public fun <init> (Ljava/lang/String;Lorg/dexpace/sdk/core/http/response/Response;Ljava/lang/Object;)V
-	public fun <init> (Ljava/lang/String;Lorg/dexpace/sdk/core/http/response/Response;Ljava/lang/Object;Ljava/lang/Throwable;)V
-	public synthetic fun <init> (Ljava/lang/String;Lorg/dexpace/sdk/core/http/response/Response;Ljava/lang/Object;Ljava/lang/Throwable;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
-	public final fun getResponse ()Lorg/dexpace/sdk/core/http/response/Response;
-	public final fun getValue ()Ljava/lang/Object;
-	public final fun isRetryable ()Z
-}
-
 public final class org/dexpace/sdk/core/http/response/LoggableResponseBody : org/dexpace/sdk/core/http/response/ResponseBody {
 	public fun <init> (Lorg/dexpace/sdk/core/http/response/ResponseBody;)V
 	public fun <init> (Lorg/dexpace/sdk/core/http/response/ResponseBody;Lorg/dexpace/sdk/core/io/IoProvider;)V
@@ -1319,20 +1309,22 @@ public class org/dexpace/sdk/core/http/response/exception/GoneException : org/de
 	public synthetic fun <init> (Lorg/dexpace/sdk/core/http/response/Response;Ljava/lang/String;Ljava/lang/Throwable;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 }
 
-public abstract class org/dexpace/sdk/core/http/response/exception/HttpException : java/lang/RuntimeException {
+public abstract class org/dexpace/sdk/core/http/response/exception/HttpException : java/lang/RuntimeException, org/dexpace/sdk/core/http/response/exception/Retryable {
 	public static final field Companion Lorg/dexpace/sdk/core/http/response/exception/HttpException$Companion;
 	public static final field DEFAULT_SNAPSHOT_BYTES I
 	public fun <init> (Lorg/dexpace/sdk/core/http/response/Status;Lorg/dexpace/sdk/core/http/common/Headers;Lorg/dexpace/sdk/core/http/response/ResponseBody;)V
 	public fun <init> (Lorg/dexpace/sdk/core/http/response/Status;Lorg/dexpace/sdk/core/http/common/Headers;Lorg/dexpace/sdk/core/http/response/ResponseBody;Ljava/lang/String;)V
 	public fun <init> (Lorg/dexpace/sdk/core/http/response/Status;Lorg/dexpace/sdk/core/http/common/Headers;Lorg/dexpace/sdk/core/http/response/ResponseBody;Ljava/lang/String;Ljava/lang/Throwable;)V
-	public synthetic fun <init> (Lorg/dexpace/sdk/core/http/response/Status;Lorg/dexpace/sdk/core/http/common/Headers;Lorg/dexpace/sdk/core/http/response/ResponseBody;Ljava/lang/String;Ljava/lang/Throwable;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun <init> (Lorg/dexpace/sdk/core/http/response/Status;Lorg/dexpace/sdk/core/http/common/Headers;Lorg/dexpace/sdk/core/http/response/ResponseBody;Ljava/lang/String;Ljava/lang/Throwable;Ljava/lang/Object;)V
+	public synthetic fun <init> (Lorg/dexpace/sdk/core/http/response/Status;Lorg/dexpace/sdk/core/http/common/Headers;Lorg/dexpace/sdk/core/http/response/ResponseBody;Ljava/lang/String;Ljava/lang/Throwable;Ljava/lang/Object;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun bodySnapshot ()[B
 	public final fun bodySnapshot (I)[B
 	public static synthetic fun bodySnapshot$default (Lorg/dexpace/sdk/core/http/response/exception/HttpException;IILjava/lang/Object;)[B
 	public final fun getBody ()Lorg/dexpace/sdk/core/http/response/ResponseBody;
 	public final fun getHeaders ()Lorg/dexpace/sdk/core/http/common/Headers;
-	public final fun getRetryable ()Z
 	public final fun getStatus ()Lorg/dexpace/sdk/core/http/response/Status;
+	public final fun getValue ()Ljava/lang/Object;
+	public fun isRetryable ()Z
 }
 
 public final class org/dexpace/sdk/core/http/response/exception/HttpException$Companion {
@@ -1357,12 +1349,12 @@ public class org/dexpace/sdk/core/http/response/exception/MethodNotAllowedExcept
 	public synthetic fun <init> (Lorg/dexpace/sdk/core/http/response/Response;Ljava/lang/String;Ljava/lang/Throwable;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 }
 
-public class org/dexpace/sdk/core/http/response/exception/NetworkException : java/io/IOException {
+public class org/dexpace/sdk/core/http/response/exception/NetworkException : java/io/IOException, org/dexpace/sdk/core/http/response/exception/Retryable {
 	public fun <init> ()V
 	public fun <init> (Ljava/lang/String;)V
 	public fun <init> (Ljava/lang/String;Ljava/lang/Throwable;)V
 	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/Throwable;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
-	public final fun getRetryable ()Z
+	public fun isRetryable ()Z
 }
 
 public class org/dexpace/sdk/core/http/response/exception/NotFoundException : org/dexpace/sdk/core/http/response/exception/HttpException {
@@ -1386,6 +1378,10 @@ public class org/dexpace/sdk/core/http/response/exception/RequestTimeoutExceptio
 	public synthetic fun <init> (Lorg/dexpace/sdk/core/http/response/Response;Ljava/lang/String;Ljava/lang/Throwable;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 }
 
+public abstract interface class org/dexpace/sdk/core/http/response/exception/Retryable {
+	public abstract fun isRetryable ()Z
+}
+
 public class org/dexpace/sdk/core/http/response/exception/ServerErrorException : org/dexpace/sdk/core/http/response/exception/HttpException {
 	public fun <init> (Lorg/dexpace/sdk/core/http/response/Response;)V
 	public fun <init> (Lorg/dexpace/sdk/core/http/response/Response;Ljava/lang/String;)V
@@ -2091,6 +2087,12 @@ public abstract interface class org/dexpace/sdk/core/pipeline/step/ResponseRecov
 	public abstract fun invoke (Lorg/dexpace/sdk/core/pipeline/ResponseOutcome;)Lorg/dexpace/sdk/core/pipeline/ResponseOutcome;
 }
 
+public final class org/dexpace/sdk/core/pipeline/step/ThrowOnHttpErrorStep : org/dexpace/sdk/core/pipeline/step/ResponsePipelineStep {
+	public static final field INSTANCE Lorg/dexpace/sdk/core/pipeline/step/ThrowOnHttpErrorStep;
+	public synthetic fun execute (Ljava/lang/Object;Lorg/dexpace/sdk/core/http/context/DispatchContext;)Ljava/lang/Object;
+	public fun execute (Lorg/dexpace/sdk/core/http/response/Response;Lorg/dexpace/sdk/core/http/context/DispatchContext;)Lorg/dexpace/sdk/core/http/response/Response;
+}
+
 public final class org/dexpace/sdk/core/pipeline/step/retry/BackoffCalculator {
 	public static final field INSTANCE Lorg/dexpace/sdk/core/pipeline/step/retry/BackoffCalculator;
 	public static final fun computeDelay (ILorg/dexpace/sdk/core/pipeline/step/retry/RetrySettings;)Ljava/time/Duration;