001/* 002 * Copyright 2015-2022 Transmogrify LLC, 2022-2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.pyranid; 018 019import org.jspecify.annotations.NonNull; 020import org.jspecify.annotations.Nullable; 021 022import javax.annotation.concurrent.ThreadSafe; 023import java.util.Optional; 024 025/** 026 * Converts non-secure bound parameter values into safe display values for diagnostics. 027 * <p> 028 * This is display-only: it does not change what is bound to the database. Pyranid never invokes a 029 * {@code ParameterRedactor} for {@link SecureParameter} values; {@link SecureParameter#getMask()} always wins. For batch 030 * executions, Pyranid renders a bounded batch summary and does not invoke this redactor for individual batch values. 031 * <p> 032 * <strong>Scope.</strong> A {@code ParameterRedactor} governs Pyranid's rendering of its own {@code parameters=[...]} 033 * diagnostic list only. It does <em>not</em> reach text the database driver itself produces: driver error messages can 034 * echo bound values (for example, constraint-violation detail), and only values explicitly wrapped with 035 * {@link Parameters#secure} trigger Pyranid's best-effort scrub of driver-echoed text - see {@link SecureParameter} 036 * for that mechanism and its limits. Note that under the default {@link #none()}, non-secure values render verbatim 037 * in statement logs and exception text; configure {@link #redactAll()} or a custom redactor if diagnostics may leave 038 * a trusted boundary. 039 * <p> 040 * Implementations return a non-null Optional containing the safe display value. An empty Optional renders as 041 * {@code null} in the same parameter slot; it does not fall back to the original value or omit the slot. 042 * Direct diagnostic rendering propagates failures if an implementation throws or returns a null Optional. When 043 * rendering is part of reporting a SQL failure, Pyranid uses its fail-closed parameter-display fallback and retains 044 * the original SQL failure, with the rendering failure suppressed. 045 * 046 * @author <a href="https://www.revetkn.com">Mark Allen</a> 047 * @since 4.4.0 048 */ 049@ThreadSafe 050@FunctionalInterface 051public interface ParameterRedactor { 052 /** 053 * Redacts a single non-secure parameter for diagnostics. 054 * <p> 055 * Since 4.9.0 this method returns a non-null Optional rather than a nullable Object. Implementations, lambdas 056 * and direct callers compiled against the earlier contract must be updated and recompiled. 057 * <p> 058 * Read the original binding name with 059 * {@code statementContext.getParameterNames().get(parameterIndex)}. Names have no leading colon; 060 * repeated bindings and IN-list elements retain their original name, and unknown names are {@code null}. 061 * For example, {@code "password".equals(name)} is a null-safe name check. This method is the single 062 * redaction entry point for diagnostics, direct callers and lambda decorators. 063 * 064 * @param statementContext current SQL context 065 * @param parameterIndex zero-based index into {@link StatementContext#getParameters()} after IN-list expansion 066 * @param parameter parameter value to render safely 067 * @return the safe display value, or an empty Optional to render {@code null}; never {@code null} 068 */ 069 @NonNull 070 Optional<Object> redactParameter(@NonNull StatementContext<?> statementContext, 071 @NonNull Integer parameterIndex, 072 @Nullable Object parameter); 073 074 /** 075 * Acquires the default redactor, which renders non-secure values verbatim for non-batch executions. 076 * 077 * @return the default redactor 078 */ 079 @NonNull 080 static ParameterRedactor none() { 081 return (statementContext, parameterIndex, parameter) -> Optional.ofNullable(parameter); 082 } 083 084 /** 085 * Acquires a redactor that masks every non-secure value as {@code <redacted>}. 086 * 087 * @return a redactor that masks every non-secure value 088 */ 089 @NonNull 090 static ParameterRedactor redactAll() { 091 return (statementContext, parameterIndex, parameter) -> Optional.of(SecureParameterSupport.DEFAULT_MASK); 092 } 093}