001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.rest.client;
018
019import static org.apache.juneau.commons.utils.Shorts.*;
020
021import java.net.*;
022import java.time.*;
023import java.util.*;
024
025import org.apache.juneau.http.remote.*;
026
027/**
028 * A fully-resolved, transport-layer HTTP request.
029 *
030 * <p>
031 * All values (URIs, headers, bodies) are evaluated before this object is constructed — suppliers have been
032 * invoked, {@code null}-valued parts have been filtered, and the final URI has been assembled with query
033 * parameters and path substitutions applied.
034 *
035 * <p>
036 * Transport implementations receive a {@link TransportRequest} and are responsible for executing it against
037 * the remote server, returning a {@link TransportResponse}.
038 *
039 * @since 9.2.1
040 */
041public final class TransportRequest {
042
043   // Methods defined as idempotent by RFC 7231 §4.2.2 — replaying them cannot change server state beyond a
044   // single application of the request, so a transport may safely re-send them once on a fresh connection.
045   private static final Set<String> IDEMPOTENT_METHODS = Set.of("GET", "HEAD", "PUT", "DELETE", "OPTIONS", "TRACE");
046
047   private final String method;
048   private final URI uri;
049   private final List<TransportHeader> headers;
050   private final TransportBody body;
051   private final Duration timeout;
052   private final boolean policyEnforced;
053   private final boolean allowPrivateUrls;
054   private final RemoteUrlPolicy.AllowedRanges allowedAddressRanges;
055   private final Set<String> redirectForwardHeaders;
056
057   private TransportRequest(Builder builder) {
058      this.method = reqnn("method", builder.method);
059      this.uri = reqnn("uri", builder.uri);
060      this.headers = List.copyOf(builder.headers);
061      this.body = builder.body;
062      this.timeout = builder.timeout;
063      this.policyEnforced = builder.policyEnforced;
064      this.allowPrivateUrls = builder.allowPrivateUrls;
065      this.allowedAddressRanges = builder.allowedAddressRanges;
066      this.redirectForwardHeaders = Set.copyOf(builder.redirectForwardHeaders);
067   }
068
069   /**
070    * Returns the extra header names that may be replayed against another origin.
071    *
072    * <p>
073    * A redirect to another origin keeps only the headers on the {@link RedirectSecurity#forwardOnCrossOrigin() built-in
074    * forward list} plus these names, set with {@link RestClient.Builder#redirectForwardHeaders(String...)}.  Compare names
075    * case-insensitively.
076    *
077    * @return An unmodifiable set. Never <jk>null</jk>.
078    */
079   public Set<String> getRedirectForwardHeaders() {
080      return redirectForwardHeaders;
081   }
082
083   /** Returns a new {@link Builder}. */
084   public static Builder builder() {
085      return new Builder();
086   }
087
088   /**
089    * Returns the HTTP method (e.g. {@code "GET"}, {@code "POST"}).
090    *
091    * @return The method. Never <jk>null</jk>.
092    */
093   public String getMethod() {
094      return method;
095   }
096
097   /**
098    * Returns the fully-resolved request URI, including query string.
099    *
100    * @return The URI. Never <jk>null</jk>.
101    */
102   public URI getUri() {
103      return uri;
104   }
105
106   /**
107    * Returns all request headers in the order they should be sent.
108    *
109    * @return An unmodifiable list. Never <jk>null</jk>.
110    */
111   public List<TransportHeader> getHeaders() {
112      return headers;
113   }
114
115   /**
116    * Returns the first header with the given name (case-insensitive), or {@code null} if absent.
117    *
118    * @param name The header name. Must not be <jk>null</jk>.
119    * @return The first matching header, or <jk>null</jk> if absent.
120    */
121   public TransportHeader getFirstHeader(String name) {
122      return headers.stream()
123         .filter(h -> eqic(h.name(), name))
124         .findFirst()
125         .orElse(null);
126   }
127
128   /**
129    * Returns the request body, or {@code null} if this is a body-less request (e.g. GET, HEAD).
130    *
131    * @return The body, possibly <jk>null</jk>.
132    */
133   public TransportBody getBody() {
134      return body;
135   }
136
137   /**
138    * Returns {@code true} if this request can be transparently re-sent once after a stale-connection failure.
139    *
140    * <p>
141    * A pooled keep-alive socket can be torn down by the server between requests; when a transport then reuses
142    * that socket the first write fails before any response is received (e.g. an early {@code EOF} or a
143    * {@code NoHttpResponseException}).  Such a failure is safe to retry on a fresh connection <b>only</b> when
144    * replaying the request cannot cause a duplicate side effect, which requires both of:
145    * <ul>
146    *    <li>an <a class="doclink" href="https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2">idempotent</a>
147    *       HTTP method ({@code GET}, {@code HEAD}, {@code PUT}, {@code DELETE}, {@code OPTIONS}, {@code TRACE}) — never
148    *       {@code POST} or any other non-idempotent method, and
149    *    <li>a body that is either absent or {@link TransportBody#isRepeatable() repeatable}, so the exact same bytes
150    *       can be written again.
151    * </ul>
152    *
153    * <p>
154    * When in doubt this returns {@code false} — the caller must fail closed rather than risk double-executing a
155    * request.
156    *
157    * @return {@code true} if the request is provably safe to replay once.
158    */
159   public boolean isSafeToReplay() {
160      return IDEMPOTENT_METHODS.contains(method.toUpperCase(Locale.ROOT)) && (body == null || body.isRepeatable());
161   }
162
163   /**
164    * Returns the per-call response timeout, or {@code null} if none was set.
165    *
166    * <p>
167    * A {@code null} value means the transport's own default applies.  Connect timeouts remain a client-level
168    * concern.  All built-in transports honor this value (JDK, Apache HttpClient 4.5/5, OkHttp, Jetty and the mock transport).
169    *
170    * @return The response timeout, possibly <jk>null</jk>.
171    */
172   public Duration getTimeout() {
173      return timeout;
174   }
175
176   /**
177    * Returns {@code true} if this request originated from a {@code @Remote}/{@code @Url} call and is subject to
178    * the SSRF guardrail (see {@code org.apache.juneau.http.remote.RemoteUrlPolicy}).
179    *
180    * <p>
181    * Ordinary (non-{@code @Remote}) requests built directly via {@code RestClient.get(url)} etc. are never
182    * policy-covered.
183    *
184    * @return {@code true} if the SSRF guardrail applies to this request.
185    */
186   public boolean isPolicyEnforced() {
187      return policyEnforced;
188   }
189
190   /**
191    * Returns {@code true} if the {@code allowPrivateUrls} opt-in is in effect for this request, disabling the
192    * deny-private / pin-on-connect / redirect-revalidation checks (the {@code http}/{@code https} scheme
193    * requirement still applies upstream).
194    *
195    * @return {@code true} if private/loopback/link-local/metadata targets are allowed for this request.
196    */
197   public boolean isAllowPrivateUrls() {
198      return allowPrivateUrls;
199   }
200
201   /**
202    * Returns the per-client special-purpose address ranges that the SSRF guardrail re-permits for this request (see
203    * {@link RestClient.Builder#allowAddressRanges(String...)}); they are unioned with the
204    * {@value RemoteUrlPolicy#ALLOW_ADDRESS_RANGES_PROPERTY} system property.
205    *
206    * @return The allowed ranges. Never <jk>null</jk>; {@link org.apache.juneau.http.remote.RemoteUrlPolicy.AllowedRanges#NONE RemoteUrlPolicy.AllowedRanges#NONE} by default.
207    */
208   public RemoteUrlPolicy.AllowedRanges getAllowedAddressRanges() {
209      return allowedAddressRanges;
210   }
211
212   /**
213    * Returns {@code true} if the SSRF guardrail's connect-time machinery (pin-on-connect + Juneau-controlled
214    * redirect revalidation) must be applied by the transport for this request: {@link #isPolicyEnforced()} is set
215    * and {@link #isAllowPrivateUrls()} is not.
216    *
217    * @return {@code true} if the transport must pin-on-connect and manually revalidate redirects for this request.
218    */
219   public boolean isSsrfGuardActive() {
220      return policyEnforced && ! allowPrivateUrls;
221   }
222
223   // -----------------------------------------------------------------------------------------------------------------
224   // Builder
225   // -----------------------------------------------------------------------------------------------------------------
226
227   /**
228    * Fluent builder for {@link TransportRequest}.
229    *
230    * @since 9.2.1
231    */
232   public static final class Builder {
233
234      String method;
235      URI uri;
236      final List<TransportHeader> headers = l();
237      TransportBody body;
238      Duration timeout;
239      boolean policyEnforced;
240      boolean allowPrivateUrls;
241      RemoteUrlPolicy.AllowedRanges allowedAddressRanges = RemoteUrlPolicy.AllowedRanges.NONE;
242      final Set<String> redirectForwardHeaders = new LinkedHashSet<>();
243
244      private Builder() {}
245
246      /**
247       * Adds header names that may be replayed against another origin, besides
248       * {@link RedirectSecurity#forwardOnCrossOrigin()}.
249       *
250       * @param value The header names. <jk>null</jk> or empty adds nothing.
251       * @return This object.
252       */
253      public Builder redirectForwardHeaders(Collection<String> value) {
254         if (value != null)
255            redirectForwardHeaders.addAll(value);
256         return this;
257      }
258
259      /**
260       * Sets the HTTP method.
261       *
262       * @param value The method (e.g. {@code "GET"}). Must not be <jk>null</jk>.
263       * @return This object.
264       */
265      public Builder method(String value) {
266         method = value;
267         return this;
268      }
269
270      /**
271       * Sets the request URI.
272       *
273       * @param value The URI. Must not be <jk>null</jk>.
274       * @return This object.
275       */
276      public Builder uri(URI value) {
277         uri = value;
278         return this;
279      }
280
281      /**
282       * Sets the request URI from a string.
283       *
284       * @param value The URI string. Must not be <jk>null</jk>.
285       * @return This object.
286       * @throws IllegalArgumentException If the string is not a valid URI.
287       */
288      public Builder uri(String value) {
289         try {
290            uri = new URI(value);
291         } catch (URISyntaxException e) {
292            throw iaex(e, "Invalid URI: %s", value);
293         }
294         return this;
295      }
296
297      /**
298       * Appends a request header.
299       *
300       * @param name The header name. Must not be <jk>null</jk>.
301       * @param value The header value. Must not be <jk>null</jk>.
302       * @return This object.
303       */
304      public Builder header(String name, String value) {
305         headers.add(TransportHeader.of(name, value));
306         return this;
307      }
308
309      /**
310       * Appends multiple request headers.
311       *
312       * @param value The headers to add. Must not be <jk>null</jk>.
313       * @return This object.
314       */
315      public Builder headers(Collection<TransportHeader> value) {
316         headers.addAll(value);
317         return this;
318      }
319
320      /**
321       * Sets the request body.
322       *
323       * @param value The body. May be <jk>null</jk> for body-less requests.
324       * @return This object.
325       */
326      public Builder body(TransportBody value) {
327         body = value;
328         return this;
329      }
330
331      /**
332       * Sets the per-call response timeout.
333       *
334       * @param value The response timeout. May be <jk>null</jk> to use the transport default.  Must otherwise be positive.
335       * @return This object.
336       * @throws IllegalArgumentException If <c>value</c> is zero or negative.
337       */
338      public Builder timeout(Duration value) {
339         if (value != null && (value.isZero() || value.isNegative()))
340            throw new IllegalArgumentException("Request timeout must be positive: " + value);
341         timeout = value;
342         return this;
343      }
344
345      /**
346       * Marks this request as originating from a {@code @Remote}/{@code @Url} call, subject to the SSRF guardrail,
347       * and records whether the {@code allowPrivateUrls} opt-in is in effect.
348       *
349       * @param policyEnforced {@code true} if this request is policy-covered.
350       * @param allowPrivateUrls {@code true} if the {@code allowPrivateUrls} opt-in disables the deny-private checks.
351       * @return This object.
352       */
353      public Builder remoteUrlPolicy(boolean policyEnforced, boolean allowPrivateUrls) {
354         this.policyEnforced = policyEnforced;
355         this.allowPrivateUrls = allowPrivateUrls;
356         return this;
357      }
358
359      /**
360       * Sets the per-client special-purpose address ranges the SSRF guardrail re-permits for this request.
361       *
362       * @param value The allowed ranges. <jk>null</jk> means none.
363       * @return This object.
364       */
365      public Builder allowedAddressRanges(RemoteUrlPolicy.AllowedRanges value) {
366         this.allowedAddressRanges = value == null ? RemoteUrlPolicy.AllowedRanges.NONE : value;
367         return this;
368      }
369
370      /**
371       * Builds and returns the {@link TransportRequest}.
372       *
373       * @return A new instance. Never <jk>null</jk>.
374       */
375      public TransportRequest build() {
376         return new TransportRequest(this);
377      }
378   }
379}