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}