feat!: developer-experience improvements across the SDK surface

[OmarAlJarrah]

Summary

The toolkit had strong internals whose ergonomics and documentation lagged behind: making a first request meant a mandatory global bootstrap, building a request meant a verbose builder with no verb shortcuts, reading a response meant null-chasing through body?.source()?.readUtf8(), and the typed error model, streaming decoders, and resilience steps that already existed were undemonstrated or missing their last-mile one-liner. Two subsystems both called themselves "pipeline," and two different classes were both named RetryStep.

This change closes those gaps across the whole surface. It is a broad, mostly-additive pass with a set of deliberate pre-1.0 breaking changes where a name or signature was worth correcting now rather than after 1.0. sdk-core keeps its zero-runtime-dependency invariant; every convenience that needs Okio or Jackson lives in an adapter module.

First-request friction

• Zero-config I/O. Io.provider now resolves a single IoProvider on the classpath via ServiceLoader, so Io.installProvider(OkioIoProvider) is optional when the Okio adapter is present. This removes the one bootstrap line every caller previously had to run before the first request or hit a runtime failure; explicit install still overrides, and 0-or-many providers still fail loudly with an actionable message.
• Turnkey pipelines. HttpPipeline.standard(transport) / HttpPipelineBuilder.appendStandardResilience() assemble redirect + retry + instrumentation with sane defaults in one call, so getting resilience no longer requires knowing and ordering the individual Default*Step classes. (The async mirror assembles retry + instrumentation; there is no async redirect step to include.)
• Installation docs. The README previously had no way to actually depend on the project. It gains an Installation section (Gradle + Maven coordinates), a per-module coordinate column, an ergonomic quick start, a "How do I…" snippet set, and a minimal SimpleGetApp sample alongside the full one — the quick start now teaches the ergonomic path instead of the manual one.

Request & response ergonomics

• Request building. The builder now defaults to GET (so build() no longer requires an explicit method and no longer throws when one is omitted) and gains verb methods (get/post/put/delete/head/patch, where the body-less verbs also clear any previously-set body); Request.get/post/put/delete/head/patch(...) static factories for the common one-liners; typed addHeader/setHeader(HttpHeaderName, String | List<String> | MediaType) overloads so callers holding a typed header name or media type no longer .toString() both by hand; and a url(URI) overload. url(String) now throws an unchecked IllegalArgumentException instead of a checked MalformedURLException, so a literal URL no longer forces a try/catch.
• Typed bodies. RequestBody.create(value, serde) serializes a typed value in one call instead of the manual serialize-then-wrap two-step; Serde.contentType() supplies the default media type so it doesn't have to be restated at every call site.
• Media types. MediaType.APPLICATION_JSON (and the other common constants) are now reachable directly on MediaType; previously the constants lived only on a separate CommonMediaTypes object, so callers reached for the parse-a-string form (a typo risk).
• Response reading. Response.isSuccessful, ResponseBody.string()/bytes(), and the five Status range predicates (isInformational, isRedirect, isClientError, isServerError, isError) remove the common null-chasing and status arithmetic; HttpExceptionFactory.isErrorStatus now delegates to Status.isError.
• Typed reads. response.deserialize(serde, Class | TypeRef) and response.parsedWith(jsonHandler(serde, T::class.java)).value() stream and close the body. The new dependency-free TypeRef<T> enables parametric decode (List<User>) without a Jackson import at the call site (Deserializer gains default TypeRef methods; the Jackson adapter resolves the generic type), and a new jsonHandlerOrThrow(...) handler decodes on 2xx and throws the mapped HttpException (with a bounded, buffered error body) on non-2xx.

Error handling

• Typed errors on demand. HttpPipelineBuilder.throwOnHttpError() (and its async mirror) maps 4xx/5xx to the typed HttpException hierarchy so callers stop hand-writing check(status.isSuccess). It runs at a new outermost Stage.PRE_REDIRECT deliberately: evaluating the response at the outermost stage means it only ever sees the final response, so it never throws on an intermediate 3xx redirect hop and never preempts a retryable 5xx that the inner retry step would have recovered.
• Call-site mapping. Response.throwOnError() does the same at a call site, buffering the error body (bounded to 1 MiB) so the exception's body survives the response being closed; HttpException.bodyAs(...) decodes a typed error payload and closes the body.
• Transport failures. Both reference transports now surface transport-level failures as NetworkException (which extends IOException, so existing catch (IOException) still works) so the documented NetworkException contract is real, and both retry stacks now classify the same failure identically.

Configuration & per-request control

• Per-request overrides. A single slow or non-standard endpoint previously needed a whole second transport + pipeline. The new RequestOptions carrier (send(request, options)) threads a per-call timeout and maxRetries override — plus an opaque tags map for correlation/extension — through the pipeline to the transports and the retry step, with fallback to the configured defaults. The SPI overloads (execute/executeAsync(request, options)) are default methods, so existing third-party transports keep compiling.
• Config surface. HttpRetryOptions, HttpInstrumentationOptions, and HttpRedirectOptions gain builders (Builder<T> + newBuilder()) so a Java caller can set the seventh field without positionally re-supplying the six defaults before it. HttpRetryOptions.fromConfiguration(...) wires the previously-orphaned max-retry key; the JDK transport now defaults to a 10s connect timeout (it was unbounded, deviating from the documented default); both transports gain opt-in proxyFromEnvironment().

Java interop

• Value-class demotion. ETag and HttpRange are demoted from @JvmInline value class to plain final classes: their @JvmInline name mangling (parse-1jReFK8, ifMatch-a6HYibk, …) produced identifiers Java can't call, making the whole typed conditional-request / range surface unreachable. They keep value semantics and gain String overloads on RequestConditions.Builder.ifMatch/ifNoneMatch.
• SAM extractors. Pagination strategies take dedicated functional interfaces (CursorExtractor / LinkExtractor / PageNumberExtractor) instead of a raw kotlin.jvm.functions.Function1, which is opaque and awkward to implement from Java.
• Fail-fast pillars. Adding a second, distinct step to a pillar stage now throws IllegalStateException (naming the stage and pointing at replace<T>()) instead of silently warning-and-replacing, so a mis-assembled pipeline fails at build time instead of dropping a step.

Async

• Terminal helper. CompletableFuture<Response>.handleWith(handler) replaces the error-prone whenComplete { r, e -> … r.use{} } pattern every async caller re-wrote: it applies the handler, closes the response on both paths, and unwraps CompletionException so the caller sees the real cause. AsyncHttpPipeline.sendAsync(request, handler) adds the typed overload.
• Cancellation parity. HttpClient.asAsync(executor) and HttpPipeline.toAsync(executor) now share one interrupting-future path, so cancel(true) interrupts the blocking send on either bridge (asAsync previously leaked the running request).

Naming

• Pipelines are transports. HttpPipeline / AsyncHttpPipeline now implement the HttpClient / AsyncHttpClient SPIs (an additive public-supertype change), so a fully-configured pipeline can drive pagination or nest as a transport — its steps run instead of the raw transport.
• Recovery stack renamed. The recovery-layer stack is renamed so it can no longer be confused with the user-facing pipeline: ExecutionPipeline → RecoveryChain, RequestPipeline/ResponsePipeline → RequestRecoveryChain/ResponseRecoveryChain (and their requestChain/responseChain members), the recovery RetryStep/ThrowOnHttpErrorStep → RetryRecovery/ThrowOnHttpErrorRecovery (ending the two duplicate simple-name collisions with the stage steps), and ClientIdentityStep drops its redundant public apply(request) so there is a single transform verb.

Breaking changes

Pre-1.0 alpha; source/binary breaks are expected. The notable ones:

• url(String) no longer declares MalformedURLException (Java callers that caught it must drop the catch).
• ETag/HttpRange are no longer @JvmInline value classes (their mangled member names change).
• Pagination strategy constructors take the new SAM extractor types instead of Function1.
• Adding a second distinct pillar step throws instead of replacing.
• The recovery-stack types are renamed (RecoveryChain/RetryRecovery/ThrowOnHttpErrorRecovery, requestChain/responseChain), and ClientIdentityStep.apply(request) is removed.
• jsonBody(serde, value) is removed in favor of the core RequestBody.create(value, serde) (it was a redundant pass-through with reversed argument order and a misleading name).

API snapshots are regenerated accordingly.

Behavior changes (source/binary compatible)

• JacksonSerde.from(mapper) now operates on a defensive mapper.copy() and registers TristateModule by default (with a registerTristate opt-out overload): a bare caller-supplied mapper silently corrupted Tristate PATCH payloads (absent vs. explicit-null), and the call no longer mutates the caller's mapper.
• Per-call RequestOptions.maxRetries with a negative value now falls back to the configured default, matching how a negative configured value is already clamped.
• The builder delete() clears a previously-set body, matching get()/head().

Testing

Full gated build green: every module's tests, ktlint, detekt, allWarningsAsErrors, binary-compatibility (apiCheck), the aggregate 80% Kover floor, and the R8 shrink-survival guard. New behavior is covered by unit tests per area; the sdk-example sample and its smoke test run against the new APIs.

Correctness and hardening follow-ups

A close read of the DX surface above surfaced a set of correctness, resource-safety, security, and
cross-transport-consistency gaps in the new conveniences (and a few latent ones they newly exposed).
This section folds in the fixes. They are grouped by area; each is stated as the problem and the change.
The full gated build — every module's tests, ktlint, detekt, allWarningsAsErrors, apiCheck, the 80%
Kover floor, and the R8 shrink-survival guard — is green, and API snapshots are regenerated.

Security & logging

• URL-valued headers were logged verbatim. Location (and Content-Location) sat in the default
  instrumentation allow-list, so their values — full URLs — were written to logs unredacted, bypassing
  the UrlRedactor that redacts url.full. Because logging runs inside the redirect loop, an OAuth
  302 Location: …?code=…, a pre-signed download URL, or an implicit-flow fragment token landed in
  plaintext. These headers are now routed through UrlRedactor (new redactUrlValue, handling absolute
  and relative values) before logging, so the query/fragment credentials are redacted while the host/path
  stays visible for diagnostics.

Retry, recovery & cancellation

• Read timeouts were misclassified as cancellation. SocketTimeoutException extends
  InterruptedIOException, so both retry steps treated a plain read timeout as a cancellation and never
  retried it (and, on the sync path, set the caller thread's interrupt flag). Socket timeouts are now
  excluded from the interrupt carve-out and left to normal retry classification.
• Typed exceptions were buried under IOException. DefaultRetryStep wrapped every non-IOException
  terminal failure in IOException("HTTP pipeline failure"), so when a pipeline carrying
  throwOnHttpError() was used as another pipeline's transport, the typed HttpException was destroyed as
  it crossed the outer retry step. Unchecked exceptions now propagate as-is (they do not violate the
  @Throws(IOException) contract), keeping the typed exception catchable.
• Cancelled async calls kept retrying. DefaultAsyncRetryStep did not check the returned future before
  scheduling the next attempt, so a cancelled call kept issuing network requests. The retry loop and both
  completion handlers now stop and close any in-flight response once the future is done.
• Status-based retries stopped after one re-send. The recovery-layer RetryRecovery treated any
  response from a re-sent attempt as terminal, so a 503, 503, 200 sequence returned the raw second 503
  instead of retrying to the 200. Re-sent responses are now re-classified: a status in
  retryableStatuses is mapped to the matching HttpException (body buffered into a bounded, replayable
  copy, connection released), so retries continue and the terminal outcome is a typed exception.
• retryableStatuses could only narrow. RetryRecovery gated HttpException retries on the built-in
  classifier before consulting retryableStatuses, so a configured status the classifier did not already
  deem retryable (e.g. 425) was silently ignored. retryableStatuses is now authoritative for an
  HttpException.
• Transport-level cancellation could trigger a retry (OkHttp). A call cancelled inside OkHttp
  (dispatcher().cancelAll(), an interceptor's call.cancel()) surfaced as a retryable NetworkException
  and was re-sent. Such cancellations now complete with a non-retryable InterruptedIOException; a
  call-timeout is discriminated by exception type and stays retryable.

Resource safety

• throwOnError error bodies were single-use. The buffered exception body was consumed by the first
  read, so bodyAs(...) followed by a bodySnapshot() saw an empty body. The error body is now buffered
  into a replayable in-memory copy through a shared helper (also used by the recovery-layer error mapper, so
  the two cannot drift), and the buffer is acquired inside the body's use block so a provider-resolution
  failure still releases the connection.
• ResponseBody.create could fail a successful call on double-close. Its close() now guards against a
  second close, honouring the documented idempotent-close contract even if the wrapped source throws.
• Pagination probes leaked connections. CloseablePages buffers the page fetched by a hasNext() probe
  and now closes both the current and any prefetched page on close(), so an emptiness check or a peeking
  wrapper no longer strands a connection.
• The async→coroutines bridge dropped a response on a cancellation race. asAsyncCoroutines now closes a
  Response computed in the window where the returned future is cancelled.
• Rejected executor tasks escaped synchronously. interruptibleFuture now surfaces a
  RejectedExecutionException from a shut-down executor through the returned future rather than throwing on
  the caller's thread, and hands off cancel(true)'s interrupt under a short guard so a stale interrupt
  cannot land on a pooled thread after the task finishes.
• Auth-challenge replay could mask the real 401. AuthStep re-sent the request body on a 401 challenge
  without checking replayability; a single-use body tripped its consume-once guard and surfaced as an
  IOException. The replay is now gated on body replayability, matching the retry and redirect steps.

Type-safe decoding

• Generic decode targets erased silently. TypeRef now rejects a captured unresolved type variable at
  construction instead of resolving it to Object (which caused heap pollution and a late
  ClassCastException). The reified Deserializer/Response.deserialize extensions capture T as a
  TypeRef, so deserialize<List<User>>() routes through the generic overloads instead of the erased raw
  class. Deserializer gains a ByteArray + TypeRef overload for parity.
• A literal null JSON body NPE'd later. Jackson decode overloads that promise a non-null value now
  throw DeserializationException when the body is the JSON literal null, at the boundary rather than at
  first use.
• Response.deserialize threw outside the serde hierarchy. A null body now throws SerdeException
  rather than a raw IllegalStateException.
• deserializeAs(InputStream, …) closed the caller's stream. It now drives a per-call parser with
  auto-close disabled, matching its contract and the sibling overloads.
• jsonHandlerOrThrow mislabelled failures. decode() lets a genuine mid-stream IOException
  propagate instead of rebranding it as a codec failure; a non-2xx non-error status (e.g. a 304) is
  reported as a protocol condition with the status and ETag/Location preserved, not as a deserialization
  failure.

Cross-transport consistency

• Content-Type behaved differently per transport. The JDK transport now emits Content-Type from the
  body's media type when the caller set none (so the RequestBody.create(value, serde) pattern carries a
  Content-Type on both transports), and on OkHttp an explicit caller Content-Type header now wins over
  the body's auto-stamped type (previously BridgeInterceptor overwrote it). The residual bodyless-DELETE
Content-Length: 0 difference the java.net.http API cannot avoid is documented, as are the differing
  default response-timeout budgets and the JDK's HTTPS-CONNECT Basic-proxy-auth limitation (with its
  workaround).

Zero-config I/O under shrinking

• R8 removed the auto-discovered provider. The sdk-io-okio3 consumer keep-rules pinned only
  OkioIoProvider, not the ServiceLoader-instantiated shim the zero-config path actually resolves, so a
  shrunk build lost its only provider. The shim and its constructor are now kept. Installing the real
  provider after the shim was auto-resolved also no longer logs a spurious mixed-provider warning.

Provider & builder ergonomics

• Io.installProvider/Io.provider are @JvmStatic (the documented Java spelling now compiles); the
  hot-path avoids a redundant volatile write; the resolution KDoc is corrected.
• HttpPipelineBuilder/AsyncHttpPipelineBuilder gain explicit flattening constructors that take a
  pipeline, so Builder(pipeline) no longer silently nests it as a raw transport; StagedSteps.reload is
  all-or-nothing so a pillar collision cannot leave a half-configured builder; the pillar-vacancy check is
  shared; close() documents that it does not close the underlying transport; AsyncHttpPipeline gains a
  sendAsync(request, options, handler) overload.

Java interop & API surface

• HttpClient.execute declares @Throws(IOException) (the SDK's NetworkException is an IOException), so
  a Java transport can throw it and a Java caller can catch it at the call site; the misplaced @Throws on
  the asBlocking() factory moves onto the wrapper's execute.
• The coroutines, Reactor, and Netty adapters gain per-call RequestOptions overloads so options are no
  longer dropped; the paginators thread RequestOptions to every page fetch.
• The two identical pagination extractor SAMs collapse into one ItemsExtractor; ETag and
  RequestConditions reject RFC-illegal values; ResponseBody.string() honours the declared charset;
  Response exposes the full status-range predicate family; the six CommonMediaTypes constants that
  overlap MediaType's delegate to it; ClientIdentityStep preserves multi-valued headers and skips blank
  tokens; a serde-encoded multipart part defaults its Content-Type; HttpRedirectOptions takes Set and
  makes a single defensive copy.

Documentation

• The README cursor-pagination example is rewritten against the real constructor signatures (the previous
  snippet did not compile); the pipeline-stage diagram includes the outermost stage; the throwOnHttpError
  and per-call-timeout semantics are stated accurately; and docs/ references to the renamed recovery-stack
  types are updated.