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.IoUtils.*; 020import static org.apache.juneau.commons.utils.Shorts.*; 021 022import java.util.*; 023import java.util.stream.*; 024 025import org.apache.juneau.http.*; 026 027/** 028 * Default {@link RestClientDebugFormatter} implementation — secure by default. 029 * 030 * <p> 031 * Request/response bodies are <b>never dumped by default</b>; dumping is a deliberate operator opt-in behind the 032 * {@code JUNEAU_REST_DEBUG_ALLOW_DUMP_BODIES} environment-variable master gate, mirroring 033 * {@code org.apache.juneau.rest.server.logging.BasicRestDebugFormatter}'s server-side contract. See 034 * {@link #bodyScrubber(RestDebugBodyScrubber)} and {@link RestClientDebugFormatter#isBodyRenderable(String)} for the 035 * rest of the pipeline. 036 * 037 * @since 10.0.0 038 */ 039public class BasicRestClientDebugFormatter implements RestClientDebugFormatter { 040 041 /** Default body capture cap, in bytes (8 KB). */ 042 public static final int DEFAULT_BODY_CAP = 8 * 1024; 043 044 /** 045 * The environment variable that gates body dumping. Keep byte-identical to 046 * {@code org.apache.juneau.rest.server.logging.BasicRestDebugFormatter}'s counterpart — the same operator-facing 047 * kill switch must protect both the server and client debug pipelines. 048 */ 049 static final String ENV_ALLOW_DUMP_BODIES = "JUNEAU_REST_DEBUG_ALLOW_DUMP_BODIES"; 050 051 /** 052 * The widened, formatter-local default set of header names whose values are masked. Starts from a copy of 053 * {@link RedactedHeaders#DEFAULT} and adds the credential-bearing headers the shared default omits. 054 * 055 * <p> 056 * Keep byte-identical to {@code org.apache.juneau.rest.server.logging.BasicRestDebugFormatter}'s counterpart. 057 */ 058 static final Set<String> DEFAULT_REDACTED_HEADERS; 059 static { 060 var s = new LinkedHashSet<>(RedactedHeaders.DEFAULT); 061 s.add("X-Auth-Token"); 062 s.add("X-Authorization"); 063 s.add("WWW-Authenticate"); 064 s.add("Referer"); 065 s.add("Location"); 066 DEFAULT_REDACTED_HEADERS = Collections.unmodifiableSet(s); 067 } 068 069 /** 070 * Cached resolution of the body-dump master gate. {@code null} means "not yet resolved"; resolution reads the 071 * environment exactly once. Not a system property, and there is no system-property fallback. 072 */ 073 private static volatile Boolean allowDumpBodiesCache; 074 075 /** The set of header names whose values are masked. */ 076 protected Set<String> redactedHeaders = DEFAULT_REDACTED_HEADERS; 077 078 /** The set of query parameter names whose values are masked in the logged URI. */ 079 protected Set<String> redactedQueryParams = RedactedQueryParams.DEFAULT; 080 081 /** Optional body scrubber applied to body text when the master gate is set. */ 082 protected RestDebugBodyScrubber bodyScrubber; 083 084 /** The body capture cap in bytes. */ 085 protected int bodyCap = DEFAULT_BODY_CAP; 086 087 /** Constructor. */ 088 public BasicRestClientDebugFormatter() { 089 /* no state to initialize */ 090 } 091 092 /** 093 * Overrides the redacted-header set. 094 * 095 * @param value The new set of header names to mask. 096 * @return This object. 097 */ 098 public BasicRestClientDebugFormatter redactedHeaders(Collection<String> value) { 099 redactedHeaders = new LinkedHashSet<>(value); 100 return this; 101 } 102 103 /** 104 * Overrides the set of query parameter names whose values are masked in the logged URI. 105 * 106 * @param value The new set of parameter names to mask (case-insensitive). Must not be <jk>null</jk>. 107 * @return This object. 108 */ 109 public BasicRestClientDebugFormatter redactedQueryParams(Collection<String> value) { 110 redactedQueryParams = new LinkedHashSet<>(value); 111 return this; 112 } 113 114 /** 115 * Extends the set of masked query parameter names additively (keeps the built-in protections). 116 * 117 * @param value The parameter names to add (case-insensitive). Must not be <jk>null</jk>. 118 * @return This object. 119 */ 120 public BasicRestClientDebugFormatter addRedactedQueryParams(Collection<String> value) { 121 var s = new LinkedHashSet<>(redactedQueryParams); 122 s.addAll(value); 123 redactedQueryParams = s; 124 return this; 125 } 126 127 /** 128 * Sets the body scrubber applied to body text when the {@code JUNEAU_REST_DEBUG_ALLOW_DUMP_BODIES} gate is set. 129 * 130 * <p> 131 * The scrubber only ever runs once dumping is already permitted by the gate; it chooses scrubbed-vs-raw body 132 * text. It is fail-closed: a throw or a <jk>null</jk> return yields a placeholder, never the raw body. 133 * 134 * @param value The scrubber, or <jk>null</jk> for none (the default, which dumps raw when gated). 135 * @return This object. 136 */ 137 public BasicRestClientDebugFormatter bodyScrubber(RestDebugBodyScrubber value) { 138 bodyScrubber = value; 139 return this; 140 } 141 142 /** 143 * Overrides the body capture cap. 144 * 145 * @param value The new cap in bytes. 146 * @return This object. 147 */ 148 public BasicRestClientDebugFormatter bodyCap(int value) { 149 bodyCap = value; 150 return this; 151 } 152 153 @Override /* RestClientDebugFormatter */ 154 public int bodyCap() { 155 return bodyCap; 156 } 157 158 @Override /* RestClientDebugFormatter */ 159 public String formatBasic(RestRequest req, RestResponse res) { 160 var uri = req.getUri(); 161 var method = DebugTextSanitizer.sanitize(req.getMethod()); 162 var uriStr = DebugTextSanitizer.sanitize(uri != null ? RedactedQueryParams.redactUri(uri.toString(), redactedQueryParams) : ""); 163 var sb = new StringBuilder(); 164 // Prepend the resolved correlation id (same effective-id order as the emit stamp): the confirmed echoed id 165 // when present, else the sent id. Both are already safe to interpolate (client-minted Uuid7 values are safe; 166 // a server-echoed value was sanitized server-side), so no second sanitizer pass is needed for this token. 167 var effectiveId = effectiveRequestId(req, res); 168 if (effectiveId != null) 169 sb.append("[requestId=").append(effectiveId).append("] "); 170 return sb 171 .append('[').append(res.getStatusCode()).append("] ") 172 .append("HTTP ").append(method).append(' ') 173 .append(uriStr) 174 .append(" (").append(req.getExecTime() != null ? req.getExecTime().toMillis() : 0).append("ms)") 175 .toString(); 176 } 177 178 // The confirmed echoed id when present, else the sent id. 179 private static String effectiveRequestId(RestRequest req, RestResponse res) { 180 if (res != null && res.getRequestId() != null) 181 return res.getRequestId(); 182 return req.getRequestId(); 183 } 184 185 @Override /* RestClientDebugFormatter */ 186 public String formatHeaders(RestRequest req, RestResponse res) { 187 var sb = new StringBuilder(); 188 189 var reqLen = req.getCachedContentLength(); 190 if (reqLen >= 0) 191 sb.append("\n\tRequest length: ").append(reqLen).append(" bytes"); 192 193 sb.append("\n\tResponse code: ").append(res.getStatusCode()); 194 195 var resLen = res.getCachedContentLength(); 196 if (resLen >= 0) 197 sb.append("\n\tResponse length: ").append(resLen).append(" bytes"); 198 199 var normalizedRedacted = normalizedRedactedSet(); 200 201 if (!req.getResolvedHeaders().isEmpty()) { 202 sb.append("\n---Request Headers---"); 203 for (var h : req.getResolvedHeaders()) 204 appendHeaderLine(sb, h.name(), h.value(), normalizedRedacted); 205 } 206 207 if (!res.getHeaders().isEmpty()) { 208 sb.append("\n---Response Headers---"); 209 for (var h : res.getHeaders()) 210 appendHeaderLine(sb, h.name(), h.value(), normalizedRedacted); 211 } 212 return sb.toString(); 213 } 214 215 private void appendHeaderLine(StringBuilder sb, String name, String value, Set<String> normalizedRedacted) { 216 // Order: mask (name-based, on the raw value) → escape (name, then whatever survived masking) → cap (none here). 217 var masked = isRedacted(name, normalizedRedacted) ? RedactedHeaders.REDACTED : value; 218 sb.append("\n\t").append(DebugTextSanitizer.sanitize(name)).append(": ").append(DebugTextSanitizer.sanitize(masked)); 219 } 220 221 private Set<String> normalizedRedactedSet() { 222 return redactedHeaders.stream() 223 .filter(Objects::nonNull) 224 .map(BasicRestClientDebugFormatter::normalizeHeaderName) 225 .collect(Collectors.toCollection(HashSet::new)); 226 } 227 228 private static boolean isRedacted(String name, Set<String> normalizedRedacted) { 229 return name != null && normalizedRedacted.contains(normalizeHeaderName(name)); 230 } 231 232 /** Case-folds and strips {@code -}/{@code _} and whitespace so {@code X-Auth-Token}/{@code X_Auth_Token}/{@code XAuthToken} all match. */ 233 private static String normalizeHeaderName(String name) { 234 var sb = new StringBuilder(name.length()); 235 for (var i = 0; i < name.length(); i++) { 236 var c = name.charAt(i); 237 if (c == '-' || c == '_' || Character.isWhitespace(c)) 238 continue; 239 sb.append(Character.toLowerCase(c)); 240 } 241 return sb.toString(); 242 } 243 244 @Override /* RestClientDebugFormatter */ 245 public String formatBody(RestRequest req, RestResponse res) { 246 var sb = new StringBuilder(); 247 // Content-Type/Content-Encoding are resolved independently per side, each from that side's own finalized, 248 // wire-order header list — never reused across sides (Risk 5). 249 var reqCt = header(req.getFirstHeader("Content-Type")); 250 var reqCe = header(req.getFirstHeader("Content-Encoding")); 251 var resCt = header(res.getFirstHeader("Content-Type")); 252 var resCe = header(res.getFirstHeader("Content-Encoding")); 253 appendBody(sb, "Request", req.getCachedContent(), req.getCachedContentLength(), reqCt, reqCe); 254 appendBody(sb, "Response", res.getCachedContent(), res.getCachedContentLength(), resCt, resCe); 255 return sb.toString(); 256 } 257 258 private static String header(TransportHeader h) { 259 return h == null ? null : h.value(); 260 } 261 262 private void appendBody(StringBuilder sb, String label, byte[] content, long totalLength, String contentType, String contentEncoding) { 263 if (content == null || content.length == 0) 264 return; 265 var byteCount = totalLength >= 0 ? totalLength : content.length; 266 var ctToken = contentTypeToken(contentType); 267 268 if (! isAllowDumpBodies()) { 269 appendPlaceholder(sb, label, byteCount, ctToken, "; set " + ENV_ALLOW_DUMP_BODIES + " to enable", "body suppressed"); 270 return; 271 } 272 273 if (! isRenderable(contentType, contentEncoding)) { 274 appendPlaceholder(sb, label, byteCount, ctToken, "; binary/non-renderable content", "body not rendered"); 275 return; 276 } 277 278 var raw = new String(content, UTF8); 279 String bodyText; 280 if (bodyScrubber != null) { 281 String scrubbed; 282 try { 283 scrubbed = bodyScrubber.scrub(contentType, raw); 284 } catch (Throwable t) { // NOSONAR - fail closed on any scrubber failure; never re-leak via the exception. 285 scrubbed = null; 286 } 287 if (scrubbed == null) { 288 appendPlaceholder(sb, label, byteCount, ctToken, "; scrubber failed", "body suppressed"); 289 return; 290 } 291 bodyText = scrubbed; 292 } else { 293 bodyText = raw; 294 } 295 296 sb.append("\n---").append(label).append(" Content---"); 297 sb.append('\n').append(DebugTextSanitizer.sanitize(bodyText, charCap())); 298 var omitted = byteCount - content.length; 299 if (omitted > 0) 300 sb.append("\n\u2026[truncated ").append(omitted).append(" bytes]"); 301 } 302 303 private void appendPlaceholder(StringBuilder sb, String label, long byteCount, String ctToken, String reason, String verb) { 304 sb.append("\n---").append(label).append(" Content---"); 305 sb.append("\n[").append(verb).append(": ").append(byteCount).append(" bytes, ").append(ctToken).append(reason).append(']'); 306 } 307 308 private String contentTypeToken(String contentType) { 309 if (ib(contentType)) 310 return "unknown"; 311 return DebugTextSanitizer.sanitize(contentType); 312 } 313 314 private boolean isRenderable(String contentType, String contentEncoding) { 315 if (! isIdentityEncoding(contentEncoding)) 316 return false; 317 return isBodyRenderable(contentType); 318 } 319 320 private static boolean isIdentityEncoding(String contentEncoding) { 321 if (contentEncoding == null) 322 return true; 323 var e = contentEncoding.trim(); 324 return e.isEmpty() || eqic(e, "identity"); 325 } 326 327 /** 328 * Returns the character-length cap for a dumped body, derived from {@link #bodyCap()}. 329 * 330 * <p> 331 * Worst-case escaping expands one byte to a 6-character {@code \\uXXXX} sequence, so the sanitized character cap 332 * is {@code bodyCap() * 6} (clamped to {@code Integer.MAX_VALUE}). Capture already bounds the raw bytes; this 333 * second layer bounds a scrubber that returns an oversized string. 334 */ 335 private int charCap() { 336 var cap = Math.max(bodyCap, 0) * 6L; 337 return cap > Integer.MAX_VALUE ? Integer.MAX_VALUE : (int) cap; 338 } 339 340 /** 341 * Returns whether body dumping is enabled by the {@code JUNEAU_REST_DEBUG_ALLOW_DUMP_BODIES} environment 342 * variable. 343 * 344 * <p> 345 * Resolved once from the environment and cached. Never reads a system property. Keep byte-identical to 346 * {@code org.apache.juneau.rest.server.logging.BasicRestDebugFormatter}'s counterpart. 347 * 348 * @return <jk>true</jk> if body dumping is enabled. 349 */ 350 static boolean isAllowDumpBodies() { 351 var v = allowDumpBodiesCache; 352 if (v == null) { 353 v = parseAllowDumpBodies(System.getenv(ENV_ALLOW_DUMP_BODIES)); 354 allowDumpBodiesCache = v; 355 } 356 return v; 357 } 358 359 /** 360 * Parses a raw gate value with trim-then-parse truthy semantics. 361 * 362 * <p> 363 * The value is trimmed first; a non-empty trimmed value enables (returns <jk>true</jk>) except case-insensitive 364 * {@code false} or {@code 0}; {@code null}/empty/all-whitespace disables. This is a fail-safe kill switch, so 365 * ambiguous values resolve to disabled. Keep byte-identical to 366 * {@code org.apache.juneau.rest.server.logging.BasicRestDebugFormatter}'s counterpart. 367 * 368 * @param raw The raw environment value. Can be <jk>null</jk>. 369 * @return <jk>true</jk> if the value enables body dumping. 370 */ 371 static boolean parseAllowDumpBodies(String raw) { 372 if (raw == null) 373 return false; 374 var t = raw.trim(); 375 if (t.isEmpty()) 376 return false; 377 return ! (eqic(t, "false") || eq(t, "0")); 378 } 379 380 /** 381 * Test-only seam for exercising both gate states without mutating the process environment. 382 * 383 * <p> 384 * Package-private and unreachable from application code, and never reads a system property. Production 385 * resolution stays env-only / read-once ({@link #isAllowDumpBodies()}). 386 * 387 * @param override {@code null} clears the cache so the next resolution re-reads the environment once; a 388 * non-<jk>null</jk> value is cached directly as the test gate state. 389 */ 390 static void resetAllowDumpBodiesForTest(Boolean override) { 391 allowDumpBodiesCache = override; 392 } 393}