Package org.apache.juneau.rest.server.logging

Interface RestDebugFormatter

All Known Implementing Classes:
BasicRestDebugFormatter, BasicTestRestDebugFormatter
public interface RestDebugFormatter
Per-tier formatter for JUL-level-driven REST debug logging.

This is the single public extension point for customizing how request/response debug records are rendered. The internal two-phase pipeline invokes the tier methods cumulatively based on the resolved logger level:

The two additive tiers default to the empty string so that a bare implementation supplying only formatBasic is additive-safe. Most implementations instead extend BasicRestDebugFormatter and override only the tier(s) they wish to change.

Secure by default

BasicRestDebugFormatter is secure by default: request/response bodies are never dumped unless the operator has deliberately set the JUNEAU_REST_DEBUG_ALLOW_DUMP_BODIES environment variable (and even then only at FINEST on renderable content). Credential-bearing header values are masked, every client-controlled string is escaped against log forging, and all output is length-bounded. See BasicRestDebugFormatter for the full contract.

The cached request/response bytes, the thrown exception, and the request execution time are reachable through the RestRequest/RestResponse accessors (RestRequest.getCachedContent(), RestRequest.getCachedContentLength(), RestRequest.getException(), RestRequest.getExecTime(), RestResponse.getCachedContent(), RestResponse.getCachedContentLength()).

See Also:
Since:
10.0.0

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_MAX_URI_LENGTH
    Default cap on the rendered URI length in the status line.

  • Method Summary

    Modifier and Type
    Method
    Description
    default int
    bodyCap()
    Returns the maximum number of request/response body bytes to capture for the FINEST-tier body rendering.
    String
    formatBasic(RestRequest req, RestResponse res)
    Renders the basic (INFO-tier) portion of the debug record.
    default String
    formatBody(RestRequest req, RestResponse res)
    Renders the body (FINEST-tier) portion of the debug record.
    default String
    formatHeaders(RestRequest req, RestResponse res)
    Renders the headers (FINE-tier) portion of the debug record.
    default boolean
    isBodyRenderable(String contentType)
    Returns true if a body with the given content type is worth rendering as text (as opposed to being binary/unknown).
    default String
    statusLine(jakarta.servlet.http.HttpServletRequest req, jakarta.servlet.http.HttpServletResponse res)
    Renders the basic status line ([status] HTTP method uri) directly from servlet objects.

  • Field Details

  • Method Details

    • formatBasic

      String formatBasic(RestRequest req, RestResponse res)
      Renders the basic (INFO-tier) portion of the debug record.

      Always invoked. Typically a single status line such as [200] HTTP GET /foo.

      Parameters:
      req - The current REST request. Never null.
      res - The current REST response. Never null.
      Returns:
      The rendered basic portion. Never null.

    • formatHeaders

      default String formatHeaders(RestRequest req, RestResponse res)
      Renders the headers (FINE-tier) portion of the debug record.

      Appended to formatBasic(RestRequest,RestResponse) when the resolved logger is at FINE-or-finer. The default returns the empty string.

      Parameters:
      req - The current REST request. Never null.
      res - The current REST response. Never null.
      Returns:
      The rendered headers portion. Never null.

    • formatBody

      default String formatBody(RestRequest req, RestResponse res)
      Renders the body (FINEST-tier) portion of the debug record.

      Appended when the resolved logger is at FINEST. Reads the cached request/response bytes. The default returns the empty string.

      Parameters:
      req - The current REST request. Never null.
      res - The current REST response. Never null.
      Returns:
      The rendered body portion. Never null.

    • statusLine

      default String statusLine(jakarta.servlet.http.HttpServletRequest req, jakarta.servlet.http.HttpServletResponse res)
      Renders the basic status line ([status] HTTP method uri) directly from servlet objects.

      Used both by formatBasic(RestRequest,RestResponse) and by the pipeline's no-operation (404/405) path, which has no RestRequest/RestResponse to render through. The method and URI are always sanitized (CR/LF and control characters escaped) so a client-controlled URI cannot forge a log line, and the rendered URI is length-capped. This default applies DEFAULT_MAX_URI_LENGTH; BasicRestDebugFormatter overrides it to apply its configurable maxUriLength.

      The query string is intentionally excluded (matching HttpServletRequest.getRequestURI()), so plaintext ?token=… disclosure is never re-introduced through this path.

      Parameters:
      req - The servlet request. Never null.
      res - The servlet response. Never null.
      Returns:
      The rendered, sanitized status line.

    • isBodyRenderable

      default boolean isBodyRenderable(String contentType)
      Returns true if a body with the given content type is worth rendering as text (as opposed to being binary/unknown).

      This is a text-vs-binary renderability predicate, not a redaction allowlist. It parses only the media type (type/subtype, ignoring parameters such as ; charset=utf-8), case-folds, and treats the following as renderable: text/*, application/json, application/xml, any +json/+xml suffix, and application/x-www-form-urlencoded. multipart/form-data is explicitly non-renderable. An absent or blank content type is conservatively treated as non-renderable.

      Content-Encoding is not visible to this one-argument predicate; a caller that dumps bodies must separately treat any non-identity encoding (e.g. gzip) as non-renderable.

      Parameters:
      contentType - The body's content type. Can be null (returns false).
      Returns:
      true if the content type is renderable as text.

    • bodyCap

      default int bodyCap()
      Returns the maximum number of request/response body bytes to capture for the FINEST-tier body rendering.

      This cap is enforced at capture time by the two-phase pipeline, so memory stays bounded even for large uploads/downloads. Defaults to 8 KB.

      Returns:
      The body capture cap in bytes.