/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.juneau.rest.client;

import static org.apache.juneau.commons.utils.Shorts.*;

import java.io.*;
import java.net.*;
import java.nio.charset.*;
import java.time.*;
import java.util.*;
import java.util.function.*;
import java.util.logging.*;

import org.apache.juneau.http.*;
import org.apache.juneau.http.entity.*;
import org.apache.juneau.http.header.*;
import org.apache.juneau.http.part.*;
import org.apache.juneau.marshall.sse.*;

/**
 * Fluent builder for a single HTTP request.
 *
 * <p>
 * Obtain instances from the {@link RestClient} factory methods (e.g. {@link RestClient#get(String)}).
 *
 * @since 9.2.1
 */
@SuppressWarnings({
   "java:S1192", // Duplicate string literals are HTTP header names and REST protocol wire values; intentional
   "java:S3776", // Cognitive complexity acceptable for request-building and dispatch logic.
   "resource" // client is not owned here; run() transfers RestResponse ownership to caller
})
public final class RestRequest {

   private final RestClient client;
   private final String method;
   private final String url;
   private final List<HttpHeader> headers = l();
   private final List<HttpPart> queryData = l();
   private final List<HttpPart> formData = l();
   private final Map<String,Object> pathData = m();
   private HttpBody body;
   private TransportBody convertedBody;
   private URI resolvedUri;
   private Duration timeout;
   // Per-request interceptors, unioned with the client-level interceptors at run() time.
   private final List<RestCallInterceptor> requestInterceptors = l();
   private List<TransportHeader> resolvedHeaders = List.of();
   private byte[] cachedContent;
   private long cachedContentLength = -1;
   private Throwable exception;
   private Duration execTime;
   private boolean policyEnforced;
   private boolean allowPrivateUrls;
   private final List<String> redirectForwardHeaders = l();
   // The X-Request-Id correlation id sent on this request, captured at onInit (minted or caller-supplied).  Read at
   // debug-emit time as a stored field — never via a live LogContext scope that may not survive to emission.
   private String requestId;

   RestRequest(RestClient client, String method, String url) {
      this.client = client;
      this.method = method;
      this.url = url;
      // Inherit client defaults
      this.headers.addAll(client.defaultHeaders);
      this.queryData.addAll(client.defaultQueryData);
   }

   // --------------------------------------------------
   // Header
   // --------------------------------------------------

   /**
    * Adds request headers.
    *
    * @param value The headers to add. Must not be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest headers(HttpHeader... value) {
      headers.addAll(Arrays.asList(value));
      return this;
   }

   /**
    * Adds a request header.
    *
    * @param name The header name. Must not be <jk>null</jk>.
    * @param value The header value. May be <jk>null</jk> to omit.
    * @return This object.
    */
   public RestRequest header(String name, String value) {
      headers.add(HttpHeaderBean.of(name, value));
      return this;
   }

   /**
    * Adds a request header with a lazy value.
    *
    * @param name The header name. Must not be <jk>null</jk>.
    * @param value Supplier for the value. Must not be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest header(String name, Supplier<String> value) {
      headers.add(HttpHeaderBean.of(name, value));
      return this;
   }

   /**
    * Adds a <c>No-Trace: true</c> header, asking the server to keep the stack trace of a failed call out of its log.
    *
    * <p>
    * The server still logs the one-line access record; only the attached exception is omitted.
    *
    * @return This object.
    */
   public RestRequest noTrace() {
      return header(NoTrace.NAME, "true");
   }

   /**
    * Returns <jk>true</jk> if a header with the given name (case-insensitive) is already set on this request.
    *
    * <p>
    * Used by the next-gen remote-proxy engine to honor the precedence of a caller-supplied
    * {@code @Header} parameter over an annotation-declared {@code accept}/{@code contentType} attribute.
    *
    * @param name The header name. Must not be <jk>null</jk>.
    * @return <jk>true</jk> if the header is present.
    */
   public boolean hasHeader(String name) {
      return headers.stream().anyMatch(h -> eqic(name, h.getName()));
   }

   // --------------------------------------------------
   // Query
   // --------------------------------------------------

   /**
    * Adds query parameters.
    *
    * @param value The parts to add. Must not be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest queryData(HttpPart... value) {
      queryData.addAll(Arrays.asList(value));
      return this;
   }

   /**
    * Adds a query parameter.
    *
    * @param name The parameter name. Must not be <jk>null</jk>.
    * @param value The parameter value. May be <jk>null</jk> to omit.
    * @return This object.
    */
   public RestRequest queryData(String name, String value) {
      queryData.add(HttpPartBean.of(name, value));
      return this;
   }

   /**
    * Adds a query parameter with a lazy value.
    *
    * @param name The parameter name. Must not be <jk>null</jk>.
    * @param value Supplier for the value. Must not be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest queryData(String name, Supplier<String> value) {
      queryData.add(HttpPartBean.of(name, value));
      return this;
   }

   // --------------------------------------------------
   // Form data
   // --------------------------------------------------

   /**
    * Adds form fields (for {@code application/x-www-form-urlencoded} bodies).
    *
    * @param value The parts to add. Must not be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest formData(HttpPart... value) {
      formData.addAll(Arrays.asList(value));
      return this;
   }

   /**
    * Adds a form field.
    *
    * @param name The field name. Must not be <jk>null</jk>.
    * @param value The field value. May be <jk>null</jk> to omit.
    * @return This object.
    */
   public RestRequest formData(String name, String value) {
      formData.add(HttpPartBean.of(name, value));
      return this;
   }

   // --------------------------------------------------
   // Path substitution
   // --------------------------------------------------

   /**
    * Adds path variable substitutions for URI templates (e.g. replaces {@code {id}} in the URL).
    *
    * @param value The path parts to apply. Must not be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest pathData(HttpPart... value) {
      for (var p : value)
         pathData.put(p.getName(), p.getValue());
      return this;
   }

   /**
    * Adds a path variable.
    *
    * @param name The variable name (without braces). Must not be <jk>null</jk>.
    * @param value The replacement value. May be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest pathData(String name, Object value) {
      pathData.put(name, value);
      return this;
   }

   // --------------------------------------------------
   // Body
   // --------------------------------------------------

   /**
    * Sets the request body directly from an {@link HttpBody}.
    *
    * @param value The body. May be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest body(HttpBody value) {
      body = value;
      convertedBody = null;
      return this;
   }

   /**
    * Sets the request body from an arbitrary Java object.
    *
    * <p>
    * The object is first run through the client's body converter chain. The default converters handle:
    * {@link HttpBody} (passthrough), {@link InputStream}, {@code byte[]}, and {@link File}.
    * Custom converters can be registered on the builder.
    *
    * <p>
    * If no converter matches, the object is serialized with the client's explicitly-configured default serializer
    * ({@link RestClient#getDefaultSerializer()}) and sent as a string body using the serializer's content type.  When
    * no default serializer is configured, an {@link IllegalStateException} is raised (there is no implicit JSON
    * fallback) — configure one via {@link RestClient.Builder#defaultSerializer(org.apache.juneau.marshall.serializer.Serializer)}.
    *
    * @param value The body object. May be <jk>null</jk> to clear the body.
    * @return This object.
    * @throws IOException If a converter fails or the default serializer fails.
    * @throws IllegalStateException If no converter matches and no default serializer is configured on the client.
    */
   public RestRequest body(Object value) throws IOException {
      if (value == null) {
         body = null;
         convertedBody = null;
         return this;
      }
      for (var converter : client.bodyConverters) {
         if (converter.canConvert(value)) {
            convertedBody = converter.convert(value);
            body = null;
            return this;
         }
      }
      // No converter matched: stream the POJO through the client's default serializer.
      // Mirrors classic SerializedEntity — the serializer writes straight to the transport output stream during
      // run() rather than being pre-materialized into a String/byte[].  Repeatable (re-serializes on resend), so a
      // future auto-retry can resend it; streaming bodies (InputStream/Reader) remain non-repeatable.
      var s = client.getDefaultSerializer().orElseThrow(() -> new IllegalStateException(
         "No default serializer is configured on the client.  Configure one via RestClient.Builder.defaultSerializer(...)."));
      var mt = s.getResponseContentType();
      body = SerializerBody.of(s, value, mt != null ? mt.toString() : "application/json");
      convertedBody = null;
      return this;
   }

   /**
    * Sets the request body to a token/record-streaming cursor body.
    *
    * <p>
    * Convenience for {@link #body(HttpBody) body(streamBody)} that documents streaming intent and avoids a cast.
    * The {@link RecordStreamBody} writes directly to the transport output stream during {@link #run()}, so large
    * payloads are streamed to the wire without being buffered in memory.
    *
    * <h4 class='section'>Example:</h4>
    * <p class='bjava'>
    *    <jv>client</jv>.post(<js>"/bulk-upload"</js>)
    *       .streamBodyEntity(RecordStreamBody.<jsm>records</jsm>(<jv>w</jv> -&gt; {
    *          <jk>for</jk> (Bean <jv>b</jv> : <jv>source</jv>())
    *             <jv>w</jv>.write(<jv>b</jv>);
    *       }))
    *       .run();
    * </p>
    *
    * @param value The streaming body. Must not be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest streamBodyEntity(RecordStreamBody value) {
      return body(value);
   }

   /**
    * Sets the request body to a raw string (UTF-8, {@code text/plain}).
    *
    * <p>
    * Unlike {@link #body(Object)}, this bypasses the converter chain and sends the string as-is.
    *
    * @param value The string body. May be <jk>null</jk> to clear the body.
    * @return This object.
    */
   public RestRequest bodyString(String value) {
      if (value == null) {
         body = null;
         convertedBody = null;
      } else {
         body = StringBody.of(value, "text/plain");
         convertedBody = null;
      }
      return this;
   }

   // --------------------------------------------------
   // Timeout / interceptors
   // --------------------------------------------------

   /**
    * Adds header names that may be replayed against another origin by a redirect of this request.
    *
    * <p>
    * Merged with the names set on {@link RestClient.Builder#redirectForwardHeaders(String...)}.  A redirect to another
    * origin keeps only the built-in forward list plus these names; every other caller-set header is removed.  Calls
    * accumulate.  Matching is case-insensitive.
    *
    * @param value The header names. <jk>null</jk> or empty adds nothing.
    * @return This object.
    */
   public RestRequest redirectForwardHeaders(String...value) {
      if (value != null)
         redirectForwardHeaders.addAll(Arrays.asList(value));
      return this;
   }

   /**
    * Sets a per-call response timeout for this request.
    *
    * <p>
    * Threaded onto the {@link TransportRequest}.  Intended as a response timeout; connect timeouts are otherwise a client-level setting.
    *
    * <p>
    * <b>Transport support:</b> every built-in transport honors this value, using its native per-request mechanism:
    * the JDK {@code HttpRequest} timeout, an Apache HttpClient 4.5 {@code RequestConfig} (socket + connect timeout),
    * an Apache HttpClient 5 request-scoped response timeout, an OkHttp per-call read timeout, the Jetty response-header
    * wait, and a simulated handler deadline in the mock transport.  On expiry the transport throws a
    * {@link TransportException}.  When set, it overrides the transport's own default for this request only.
    *
    * <p>
    * A non-<jk>null</jk> value must be positive; zero and negative durations are rejected (matching the JDK
    * {@code HttpRequest.timeout} contract) so every transport behaves identically.
    *
    * @param value The response timeout. May be <jk>null</jk> to use the transport default.
    * @return This object.
    * @throws IllegalArgumentException If <c>value</c> is zero or negative.
    */
   public RestRequest timeout(Duration value) {
      if (value != null && (value.isZero() || value.isNegative()))
         throw new IllegalArgumentException("Request timeout must be positive: " + value);
      timeout = value;
      return this;
   }

   /**
    * Marks this request as a {@code @Remote}/{@code @Url} call subject to the SSRF guardrail (see
    * {@code org.apache.juneau.http.remote.RemoteUrlPolicy}), and records the effective {@code allowPrivateUrls}
    * opt-in for it.
    *
    * <p>
    * Called by the {@code @Remote}-proxy invocation handler; not intended for direct use by ordinary
    * {@code RestClient.get(url)}-style calls, which are never policy-covered.
    *
    * @param enforced {@code true} if this request is policy-covered.
    * @param allowPrivateUrls {@code true} if the {@code allowPrivateUrls} opt-in is in effect for this request.
    * @return This object.
    */
   public RestRequest remoteUrlPolicy(boolean enforced, boolean allowPrivateUrls) {
      this.policyEnforced = enforced;
      this.allowPrivateUrls = allowPrivateUrls;
      return this;
   }

   /**
    * Adds per-request lifecycle interceptors.
    *
    * <p>
    * These are unioned with the client-level interceptors when the request runs: the client-level (builder)
    * interceptors fire first, then these in the order added.  The next-gen remote-proxy engine uses this to layer
    * annotation-declared interface-level then method-level interceptors after the builder-configured ones.
    *
    * @param value The interceptors to add. Must not be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest interceptors(RestCallInterceptor... value) {
      requestInterceptors.addAll(Arrays.asList(value));
      return this;
   }

   /**
    * Returns <jk>true</jk> if this request's body can be safely re-sent (retry gating).
    *
    * <p>
    * A request with no body is trivially repeatable.  Otherwise the answer is delegated to the underlying
    * body's {@link HttpBody#isRepeatable()} (or {@link TransportBody#isRepeatable()} for a pre-converted body):
    * buffered bodies (string/byte[]/file/serialized POJO) are repeatable; one-shot streaming bodies
    * ({@link InputStream}/{@link Reader}/piped) are not.
    *
    * @return <jk>true</jk> if the body is absent or repeatable.
    */
   public boolean isBodyRepeatable() {
      if (convertedBody != null)
         return convertedBody.isRepeatable();
      if (body != null)
         return body.isRepeatable();
      return true;
   }

   // --------------------------------------------------
   // Accessors (for logging / interceptors)
   // --------------------------------------------------

   /**
    * Returns the HTTP method for this request (e.g. {@code "GET"}).
    *
    * @return The method. Never <jk>null</jk>.
    */
   public String getMethod() {
      return method;
   }

   /**
    * Returns the fully resolved URI for this request, or {@code null} if {@link #run()} has not been called yet.
    *
    * @return The URI, possibly <jk>null</jk>.
    */
   public URI getUri() {
      return resolvedUri;
   }

   /**
    * Returns the headers resolved onto the transport request.
    *
    * @return The resolved headers in wire order.
    */
   public List<TransportHeader> getResolvedHeaders() {
      return resolvedHeaders;
   }

   /**
    * Returns the first resolved request header with the given name (case-insensitive), or {@code null} if absent.
    *
    * <p>
    * Reads from {@link #getResolvedHeaders()} — the finalized, wire-order list — not the pre-conversion header list
    * {@link #hasHeader(String)} uses internally for its dedup check.
    *
    * @param name The header name. Must not be <jk>null</jk>.
    * @return The first matching header, or <jk>null</jk> if absent.
    */
   public TransportHeader getFirstHeader(String name) {
      return resolvedHeaders.stream()
         .filter(h -> eqic(h.name(), name))
         .findFirst()
         .orElse(null);
   }

   /**
    * Returns request body bytes captured for debug logging (up to the configured body cap).
    *
    * @return Captured request bytes, or <jk>null</jk> if not captured.
    */
   public byte[] getCachedContent() {
      return cachedContent;
   }

   /**
    * Returns the total request body length observed during write, or {@code -1} if unknown.
    *
    * @return The total body length.
    */
   public long getCachedContentLength() {
      return cachedContentLength;
   }

   /**
    * Returns the terminal request exception, if any.
    *
    * @return The terminal exception, or <jk>null</jk>.
    */
   public Throwable getException() {
      return exception;
   }

   /**
    * Returns the measured request execution time.
    *
    * @return The request execution time, or <jk>null</jk> if unset.
    */
   public Duration getExecTime() {
      return execTime;
   }

   /**
    * Sets the {@code X-Request-Id} correlation id for this request (pre-call).
    *
    * <p>
    * Sets both the outgoing {@code X-Request-Id} header and the stored sent-id field returned by
    * {@link #getRequestId()}.  Use this to propagate a caller-owned correlation id; otherwise the built-in auto-send
    * interceptor mints one at request time (unless disabled via {@link RestClient.Builder#sendRequestId(boolean)}).
    *
    * @param value The correlation id.  Must not be <jk>null</jk>.
    * @return This object.
    * @since 10.0.0
    */
   public RestRequest requestId(String value) {
      this.requestId = reqnn("value", value);
      return header(RequestIdConstants.HEADER, value);
   }

   /**
    * Returns the {@code X-Request-Id} correlation id sent on this request.
    *
    * <p>
    * Captured at request time (minted by the auto-send interceptor, or the caller-supplied value).  Read as a stored
    * field at debug-emit time &mdash; never via a live log-context scope.
    *
    * @return The sent correlation id, or <jk>null</jk> if none was sent (e.g. {@code sendRequestId(false)}).
    * @since 10.0.0
    */
   public String getRequestId() {
      return requestId;
   }

   /**
    * Records the correlation id actually sent on this request (auto-send interceptor internal use).
    *
    * @param value The sent id.
    */
   void setSentRequestId(String value) {
      this.requestId = value;
   }

   /**
    * Returns the current value of the {@code X-Request-Id} header set on this request (case-insensitive), or
    * <jk>null</jk> if none is set (auto-send interceptor internal use).
    *
    * @return The header value, or <jk>null</jk>.
    */
   String peekRequestIdHeader() {
      return headers.stream()
         .filter(h -> eqic(RequestIdConstants.HEADER, h.getName()))
         .map(HttpHeader::getValue)
         .filter(java.util.Objects::nonNull)
         .findFirst()
         .orElse(null);
   }

   // --------------------------------------------------
   // Execute
   // --------------------------------------------------

   /**
    * Executes the request and returns the response.
    *
    * <p>
    * The caller is responsible for closing the returned {@link RestResponse}.
    *
    * @return The response. Never <jk>null</jk>.
    * @throws TransportException If a network-level error occurs.
    * @throws RestCallException If the response could not be processed.
    */
   @SuppressWarnings({
      "java:S1130" // RestCallException retained for public-API/source stability: interceptors declare 'throws Exception', so a RestCallException they raise is caught by the precise-rethrow multi-catch below and propagated unchanged; Sonar's flow analysis misses this path. Removing the throws would break callers that catch RestCallException (a sibling checked exception of TransportException).
   })
   public RestResponse run() throws TransportException, RestCallException {
      var start = Instant.now();
      RestResponse response = null;
      Throwable error = null;
      var debugLevel = RestClientDebugPipeline.resolveTier(client.debugLogger);
      var debugCap = client.debugFormatter.bodyCap();
      // Union the client-level (builder) interceptors with any per-request (interface- then
      // method-level) interceptors, preserving the order builder → interface → method.
      var effectiveInterceptors = effectiveInterceptors();
      try {
         for (var interceptor : effectiveInterceptors)
            interceptor.onInit(this);

         var transportRequest = buildTransportRequest();
         resolvedHeaders = transportRequest.getHeaders();
         if (transportRequest.getBody() == null) {
            cachedContentLength = 0;
         } else {
            cachedContentLength = transportRequest.getBody().getContentLength();
         }
         if (debugLevel == Level.FINEST)
            transportRequest = captureRequestBody(transportRequest, debugCap);
         if (transportRequest.isSsrfGuardActive() && ! client.transport.supportsUrlPolicy())
            throw new TransportException("Refusing to send a policy-covered @Remote request through a transport "
               + "that cannot honor the SSRF guardrail's connect-time contract (pin-on-connect + redirect "
               + "revalidation): " + cn(client.transport) + ".  Use a first-party transport that supports it, or "
               + "set allowPrivateUrls(true) if this is an intentional local-dev/intranet target.");
         var transportResponse = client.transport.execute(transportRequest);
         response = new RestResponse(transportResponse, client, this, debugLevel, debugCap);

         for (var interceptor : effectiveInterceptors)
            interceptor.onConnect(this, response);

         execTime = Duration.between(start, Instant.now());
         response.setExecTime(execTime);
         return response;
      } catch (TransportException | RestCallException e) {
         error = e;
         throw e;
      } catch (Exception e) {
         error = e;
         throw new TransportException("Request failed: " + e.getMessage(), e);
      } finally {
         var elapsed = Duration.between(start, Instant.now());
         execTime = elapsed;
         exception = error;
         RestResponse finalResponse = response;
         if (error != null && finalResponse != null) {
            // The response was assigned but an error after that point (e.g. a throwing onConnect
            // interceptor) means it is never returned to the caller, so the caller can never close it
            // themselves — close it here to avoid leaking the underlying connection/body.
            try {
               finalResponse.setExecTime(elapsed);
               finalResponse.close();
            } catch (IOException closeError) { // HTT: close() failing on an already-broken response is not reliably reproducible
               // suppress — best effort, and the original error is what propagates
            }
         }
         for (var interceptor : effectiveInterceptors) {
            try {
               interceptor.onClose(this, finalResponse);
            } catch (Exception e2) { // HTT: exception in onClose; hard to test reliably
               // suppress interceptor close errors — best effort
            }
         }
         if (error != null && finalResponse == null) {
            var syntheticResponse = new RestResponse(TransportResponse.builder().statusCode(0).build(), client, this, debugLevel, debugCap);
            syntheticResponse.setExecTime(elapsed);
            RestClientDebugPipeline.emit(client.debugLogger, client.debugFormatter, debugLevel, this, syntheticResponse, error);
         }
      }
   }

   /**
    * Executes this request and opens a closeable, cancellable cursor over the response as a
    * <c>text/event-stream</c>.
    *
    * <p>
    * This executes {@link #run()}, asserts a 2xx response status, then opens the response body as an event stream.
    * Non-2xx responses throw {@link RestCallException} before the body is treated as SSE.
    *
    * <p>
    * The response content type is not validated. This is intentional so callers can branch on response type
    * (for example <c>application/json</c> vs <c>text/event-stream</c>) when protocols use both.
    *
    * <p>
    * Adds an {@code Accept: text/event-stream} header only when neither this request nor inherited client default
    * headers already include {@code Accept}.
    *
    * <p>
    * The caller owns the returned {@link SseEventReader}; closing it also closes the underlying
    * {@link RestResponse} (see {@link ResponseBody#asEventStream()}). If opening the event stream fails,
    * this method best-effort closes the response before propagating.
    *
    * @return A cursor over the live event stream. Never <jk>null</jk>.
    * @throws IOException If a transport-level error occurs (typically {@link TransportException}), if the response
    *    could not be processed (typically {@link RestCallException}), or if the response has no body to open a
    *    stream over.
    */
   public SseEventReader openEventStream() throws IOException {
      if (! hasHeader("Accept"))
         header("Accept", "text/event-stream");
      var res = run();
      var opened = false;
      try {
         var r = res.assertOk().body().asEventStream();
         opened = true;
         return r;
      } finally {
         if (! opened)
            quiet(res::close);
      }
   }

   /** Returns the client-level interceptors followed by the per-request ones (builder → interface → method order). */
   private List<RestCallInterceptor> effectiveInterceptors() {
      if (requestInterceptors.isEmpty())
         return client.interceptors;
      var l = new ArrayList<RestCallInterceptor>(client.interceptors.size() + requestInterceptors.size());
      l.addAll(client.interceptors);
      l.addAll(requestInterceptors);
      return l;
   }

   @SuppressWarnings({
      "java:S3776" // Request-assembly branching is intentional and cohesive; refactoring would reduce readability without benefit.
   })
   private TransportRequest buildTransportRequest() {
      var resolvedUrl = applyPathSubstitutions(url);
      resolvedUri = appendQuery(resolvedUrl);

      var builder = TransportRequest.builder()
         .method(method)
         .uri(resolvedUri)
         .timeout(timeout)
         .remoteUrlPolicy(policyEnforced, allowPrivateUrls)
         .allowedAddressRanges(client.allowedAddressRanges)
         .redirectForwardHeaders(client.redirectForwardHeaders)
         .redirectForwardHeaders(redirectForwardHeaders);

      // Headers
      for (var h : headers) {
         var v = h.getValue();
         if (v != null)
            builder.header(h.getName(), v);
      }

      if (client.parsers != null || client.defaultParser != null) {
         var hasAccept = headers.stream().anyMatch(h -> eqic("Accept", h.getName()));
         if (! hasAccept) {
            var accept = client.getDefaultAccept();
            if (accept != null)
               builder.header("Accept", accept);
         }
      }

      // A Content-Type already present in the header list (a caller-supplied @Header param, or a constant header)
      // wins over the body's own content type, and is never duplicated by it (dedup invariant).
      var hasContentType = hasHeader("Content-Type");

      // Pre-converted body from body(Object) takes priority
      if (convertedBody != null) {
         if (convertedBody.getContentType() != null && ! hasContentType)
            builder.header("Content-Type", convertedBody.getContentType());
         builder.body(convertedBody);
      } else if (!formData.isEmpty() && body == null) {
         // Form body when form data is present and no explicit body was set
         var formBody = buildFormBody();
         if (! hasContentType)
            builder.header("Content-Type", formBody.getContentType());
         builder.body(TransportBody.of(formBody));
      } else if (body != null) {
         if (body.getContentType() != null && ! hasContentType)
            builder.header("Content-Type", body.getContentType());
         builder.body(TransportBody.of(body));
      }

      return builder.build();
   }

   private TransportRequest captureRequestBody(TransportRequest request, int cap) {
      var originalBody = request.getBody();
      if (originalBody == null) {
         cachedContent = null;
         cachedContentLength = 0;
         return request;
      }

      var wrappedBody = new HttpBody() {
         @Override
         public String getContentType() {
            return originalBody.getContentType();
         }

         @Override
         public long getContentLength() {
            return originalBody.getContentLength();
         }

         @Override
         public void writeTo(OutputStream out) throws IOException {
            var tee = new BoundedCaptureOutputStream(out, cap);
            try {
               originalBody.writeTo(tee);
            } finally {
               cachedContent = tee.getCapturedBytes();
               cachedContentLength = tee.getTotalBytesWritten();
            }
         }

         @Override
         public boolean isRepeatable() {
            return originalBody.isRepeatable();
         }
      };

      var builder = TransportRequest.builder()
         .method(request.getMethod())
         .uri(request.getUri())
         .headers(request.getHeaders())
         .body(TransportBody.of(wrappedBody))
         .timeout(request.getTimeout())
         .remoteUrlPolicy(request.isPolicyEnforced(), request.isAllowPrivateUrls())
         .allowedAddressRanges(request.getAllowedAddressRanges())
         .redirectForwardHeaders(request.getRedirectForwardHeaders());
      return builder.build();
   }

   private String applyPathSubstitutions(String template) {
      var result = template;
      Object remainder = null;
      for (var entry : pathData.entrySet()) {
         if (eq(entry.getKey(), "/*")) {
            remainder = entry.getValue();  // @PathRemainder — applied after named substitutions
            continue;
         }
         var replacement = entry.getValue() != null ? entry.getValue().toString() : "";
         result = result.replace("{" + entry.getKey() + "}", urlEncode(replacement));
      }
      if (remainder != null) {
         var r = remainder.toString();
         if (! r.isEmpty()) {
            if (result.endsWith("/*"))
               result = result.substring(0, result.length() - 2);
            if (! result.endsWith("/"))
               result += "/";
            result += urlEncodePath(r);
         }
      }
      return result;
   }

   /** URL-encodes a path remainder while preserving {@code /} segment separators. */
   private static String urlEncodePath(String value) {
      var segments = value.split("/", -1);
      var sb = new StringBuilder();
      for (var i = 0; i < segments.length; i++) {
         if (i > 0)
            sb.append('/');
         sb.append(urlEncode(segments[i]));
      }
      return sb.toString();
   }

   private URI appendQuery(String baseUrl) {
      if (queryData.isEmpty()) {
         try {
            return new URI(baseUrl);
         } catch (URISyntaxException e) {
            throw iaex(e, "Invalid URL: %s", baseUrl);
         }
      }
      var sb = new StringBuilder(baseUrl);
      var first = !baseUrl.contains("?");
      for (var part : queryData) {
         var v = part.getValue();
         if (v == null)
            continue;
         sb.append(first ? '?' : '&');
         sb.append(urlEncode(part.getName())).append('=').append(urlEncode(v));
         first = false;
      }
      try {
         return new URI(sb.toString());
      } catch (URISyntaxException e) {
         throw iaex(e, "Invalid URL: %s", sb);
      }
   }

   private HttpBody buildFormBody() {
      var sb = new StringBuilder();
      var first = true;
      for (var part : formData) {
         var v = part.getValue();
         if (v == null)
            continue;
         if (!first)
            sb.append('&');
         sb.append(urlEncode(part.getName())).append('=').append(urlEncode(v));
         first = false;
      }
      final var encoded = sb.toString();
      return new HttpBody() {
         @Override public String getContentType() { return "application/x-www-form-urlencoded"; }
         @Override public long getContentLength() { return encoded.getBytes(StandardCharsets.UTF_8).length; }
         @Override public void writeTo(OutputStream out) throws IOException { out.write(encoded.getBytes(StandardCharsets.UTF_8)); }
         @Override public boolean isRepeatable() { return true; }
      };
   }

   private static String urlEncode(String value) {
      return URLEncoder.encode(value, StandardCharsets.UTF_8);
   }

   private static final class BoundedCaptureOutputStream extends OutputStream {
      private final OutputStream delegate;
      private final ByteArrayOutputStream capture = new ByteArrayOutputStream();
      private final int cap;
      private long totalBytesWritten;

      BoundedCaptureOutputStream(OutputStream delegate, int cap) {
         this.delegate = delegate;
         this.cap = cap;
      }

      byte[] getCapturedBytes() {
         return capture.toByteArray();
      }

      long getTotalBytesWritten() {
         return totalBytesWritten;
      }

      @Override
      public void write(int b) throws IOException {
         delegate.write(b);
         totalBytesWritten++;
         if (capture.size() < cap)
            capture.write(b);
      }

      @Override
      public void write(byte[] b, int off, int len) throws IOException {
         delegate.write(b, off, len);
         totalBytesWritten += len;
         var remaining = cap - capture.size();
         if (remaining > 0)
            capture.write(b, off, Math.min(len, remaining));
      }
   }
}