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}