Make defer-outer-filter-packages configurable

Introduce a configurable web-captor.defer-outer-filter-packages property (defaulting to org.springframework.security.) so exceptions from configured package prefixes are re-thrown to outer servlet filters instead of rendered as 500s. Pass the configured list from WebCaptorProperties through AppConfig into UnhandledExceptionResponseFilter, replace reflection-based Spring Security checks with a generic cause-chain prefix check (shouldDeferToOuterFilter), and update logging. Add README documentation for the new property and comprehensive tests (unit updates, new integration test and test fixture com.acme.security.CustomDenied) to verify configurable deferral behavior.

Author: david-randoll

README.md

@@ -80,6 +80,7 @@ All properties are optional. The library works out of the box with sensible defa
 | Property | Type | Default | Description |
 |---|---|---|---|
 | `web-captor.enabled` | `boolean` | `true` | Enable or disable all HTTP capturing |
+| `web-captor.defer-outer-filter-packages` | `List<String>` | `[org.springframework.security.]` | Package prefixes whose exceptions are re-thrown for an outer servlet filter to translate. See [Defer Outer-Filter Packages](#defer-outer-filter-packages-web-captordefer-outer-filter-packages). |
 
 ### Event Details (`web-captor.event-details.*`)
 
@@ -126,6 +127,53 @@ web-captor:
       method: GET,POST
 ```
 
+### Defer Outer-Filter Packages (`web-captor.defer-outer-filter-packages`)
+
+When an exception is thrown from a controller, the captor's `UnhandledExceptionResponseFilter`
+catches it as a safety net and renders a JSON 500 body. That's the right behavior for *truly*
+unhandled exceptions — but for exceptions that a servlet filter outside the captor is supposed
+to translate (the classic example is Spring Security's `ExceptionTranslationFilter` calling
+`sendError(403)` on `AccessDeniedException`), the captor must re-throw so the outer filter can
+do its job. Otherwise you get 500s where you expected 401/403.
+
+`web-captor.defer-outer-filter-packages` is the list of package-name prefixes whose exceptions
+get re-thrown instead of rendered. The captor walks the exception's cause chain and defers if
+any frame's class name starts with one of these prefixes — subclasses are matched automatically,
+so you list package roots, not individual classes.
+
+**Default:**
+
+```yaml
+web-captor:
+  defer-outer-filter-packages:
+    - org.springframework.security.
+```
+
+This is the only namespace shipped by default because Spring Security is the only widely-used
+framework that translates exceptions in an outer servlet filter (rather than via
+`@ControllerAdvice` / `HandlerExceptionResolver`, both of which the captor handles automatically).
+
+**Extending for a custom framework:**
+
+```yaml
+web-captor:
+  defer-outer-filter-packages:
+    - org.springframework.security.   # keep this
+    - com.acme.security.              # your framework
+    - org.example.auth.               # another one
+```
+
+Any `RuntimeException` thrown from those packages — or any exception whose cause chain contains
+one — will be re-thrown by the captor so your outer filter can translate it. The library never
+needs to know about specific exception classes; the package prefix is enough.
+
+**Disabling deferral entirely** (rare — captor will catch and 500 even security exceptions):
+
+```yaml
+web-captor:
+  defer-outer-filter-packages: []
+```
+
 ---
 
 ## Captured Data

spring-web-captor/src/main/java/com/davidrandoll/spring_web_captor/config/AppConfig.java

@@ -142,19 +142,12 @@ public ErrorProperties errorProperties() {
         return new ErrorProperties();
     }
 
-    /**
-     * Registered with an order that places it OUTSIDE Spring Security's filter chain
-     * (DEFAULT_FILTER_ORDER = -100). HIGHEST_PRECEDENCE + 2 keeps it just inside the existing
-     * HttpResponseEventPublisher (HIGHEST_PRECEDENCE + 1) so the captor still observes the
-     * response we write for truly-unhandled exceptions, but well before Spring Security so
-     * its ExceptionTranslationFilter handles its own exceptions first.
-     */
     @Bean("unhandledExceptionResponseFilter")
     @Order(Ordered.HIGHEST_PRECEDENCE + 2)
     @ConditionalOnMissingBean(name = "unhandledExceptionResponseFilter", ignored = UnhandledExceptionResponseFilter.class)
     @Conditional(IsWebCaptorEnabled.class)
-    public UnhandledExceptionResponseFilter unhandledExceptionResponseFilter(ObjectMapper mapper, ErrorProperties properties) {
-        return new UnhandledExceptionResponseFilter(mapper, properties);
+    public UnhandledExceptionResponseFilter unhandledExceptionResponseFilter(ObjectMapper mapper, ErrorProperties errorProperties, WebCaptorProperties webCaptorProperties) {
+        return new UnhandledExceptionResponseFilter(mapper, errorProperties, webCaptorProperties.getDeferOuterFilterPackages());
     }
 
     @Bean("excludedPathPublishCondition")

spring-web-captor/src/main/java/com/davidrandoll/spring_web_captor/properties/WebCaptorProperties.java

@@ -8,6 +8,7 @@
 import java.util.ArrayList;
 import java.util.List;
 
+
 @Data
 @Configuration
 @ConfigurationProperties(prefix = "web-captor")
@@ -22,6 +23,30 @@ public class WebCaptorProperties {
 
     private List<ExcludedRequest> excludedEndpoints = new ArrayList<>();
 
+    /**
+     * Package-name prefixes whose exceptions should be re-thrown from
+     * {@code UnhandledExceptionResponseFilter} instead of being rendered as a 500. Used when an
+     * outer servlet filter (one that runs <em>outside</em> our captor filters in the chain) is
+     * expected to translate the exception itself — e.g. Spring Security's
+     * {@code ExceptionTranslationFilter} calling {@code sendError(403)} for
+     * {@code AccessDeniedException}.
+     *
+     * <p>The default list covers Spring Security. To extend for another framework with the same
+     * translate-in-an-outer-filter pattern, replace or augment the list via configuration:
+     *
+     * <pre>{@code
+     * web-captor:
+     *   defer-outer-filter-packages:
+     *     - org.springframework.security.
+     *     - com.acme.security.
+     * }</pre>
+     *
+     * <p>The captor walks the exception's cause chain (depth-limited, self-reference-safe) and
+     * defers if any frame's class name starts with one of these prefixes. Subclasses are matched
+     * automatically — no per-class list to maintain.
+     */
+    private List<String> deferOuterFilterPackages = new ArrayList<>(List.of("org.springframework.security."));
+
     @Data
     public static class AdditionalDetails {
         private boolean duration = true;

spring-web-captor/src/main/java/com/davidrandoll/spring_web_captor/publisher/response/UnhandledExceptionResponseFilter.java

@@ -15,69 +15,44 @@
 
 import java.io.IOException;
 import java.util.HashMap;
+import java.util.List;
 
 /**
- * Last-resort fallback that renders a JSON 500 body for exceptions that escape
- * <em>every</em> other layer of the request pipeline.
+ * Safety-net renderer for runtime exceptions that escape <em>everything</em> — no
+ * {@code HandlerExceptionResolver} claimed them inside the dispatcher, no servlet filter
+ * outside the dispatcher (e.g. Spring Security's {@code ExceptionTranslationFilter})
+ * translated them via {@code sendError}, and there is no Spring Boot {@code /error}
+ * endpoint that would render them on an error dispatch.
  *
- * <p>Why we still need a security-exception skip here: depending on how Spring Security 6's
- * {@code CompositeFilterChainProxy} composes the host application's servlet filters, this
- * filter can end up <em>inside</em> {@code ExceptionTranslationFilter}'s call to
- * {@code chain.doFilter}. In that configuration, an {@code AccessDeniedException} bubbling up
- * from the dispatcher reaches us <em>before</em> {@code ExceptionTranslationFilter} can
- * translate it to a 403/401. We detect that situation structurally — by checking whether the
- * escaped exception (or any cause in its chain) is a Spring Security exception — and
- * <em>re-throw</em> it so the outer security filter can do its job.
- *
- * <p>Detection uses a <strong>package prefix</strong> (any class in
- * {@code org.springframework.security.*}), not a hard-coded class list, so new Spring Security
- * exception subclasses in future versions are handled automatically — no maintenance required.
- *
- * <p>For every other unhandled {@code RuntimeException} we render the captor's standard 500 body.
- * If a response is already committed when an exception escapes, we re-raise rather than try to
- * write a new body — the client gets whatever the container's error handling produces (never
- * an empty response).
+ * <p>Exceptions whose class lives in any package listed in
+ * {@code web-captor.defer-outer-filter-packages} (default: Spring Security) are re-thrown
+ * instead of being rendered, so the outer translator can run. To extend for another framework
+ * with the same outer-filter-translates-via-sendError pattern, just add its root package to
+ * the property — no code change to the library needed.
  */
 @Slf4j
 @RequiredArgsConstructor
 public class UnhandledExceptionResponseFilter extends OncePerRequestFilter {
 
-    /**
-     * Detection is reflection-based at class init so spring-web-captor still works in apps
-     * that don't have spring-security on the classpath — these references stay null and the
-     * security-skip is simply inert.
-     */
-    private static final Class<?> ACCESS_DENIED_CLASS = loadClass("org.springframework.security.access.AccessDeniedException");
-    private static final Class<?> AUTHENTICATION_EXCEPTION_CLASS = loadClass("org.springframework.security.core.AuthenticationException");
-    private static final String SECURITY_PACKAGE_PREFIX = "org.springframework.security.";
-
-    private static Class<?> loadClass(String name) {
-        try {
-            return Class.forName(name);
-        } catch (ClassNotFoundException e) {
-            return null;
-        }
-    }
-
     private final ObjectMapper mapper;
     private final ErrorProperties errorProperties;
+    /**
+     * Package-name prefixes whose exceptions are deferred to an outer filter.
+     * Backed by {@code web-captor.defer-outer-filter-packages}; default is
+     * {@code [org.springframework.security.]}.
+     */
+    private final List<String> deferOuterFilterPackages;
 
     @Override
     protected void initFilterBean() {
-        log.info("UnhandledExceptionResponseFilter initialized (safety-net for truly-unhandled exceptions)");
+        log.info("UnhandledExceptionResponseFilter initialized; defer packages: {}", deferOuterFilterPackages);
     }
 
     @Override
     protected void doFilterInternal(@NonNull HttpServletRequest request, @NonNull HttpServletResponse response, @NonNull FilterChain chain) throws IOException, ServletException {
         try {
             chain.doFilter(request, response);
-            if (log.isDebugEnabled()) {
-                log.debug("UnhandledExceptionResponseFilter pass-through: status={} committed={}",
-                        response.getStatus(), response.isCommitted());
-            }
         } catch (ServletException ex) {
-            // FrameworkServlet wraps anything that escapes the dispatcher (incl. unhandled
-            // RuntimeExceptions) in a ServletException. Unwrap to the real cause for the body.
             Throwable cause = ex.getCause() != null ? ex.getCause() : ex;
             handleEscapedException(request, response, cause, ex);
         } catch (RuntimeException ex) {
@@ -86,43 +61,40 @@ protected void doFilterInternal(@NonNull HttpServletRequest request, @NonNull Ht
     }
 
     private void handleEscapedException(HttpServletRequest request, HttpServletResponse response, Throwable cause, Exception originalToRethrow) throws IOException, ServletException {
-        // 1. Defer to Spring Security: re-throw so its ExceptionTranslationFilter
-        //    (which wraps this filter in some configurations) can translate to 401/403.
-        if (shouldDeferToSecurityFilter(cause)) {
-            log.debug("Deferring Spring Security exception {} so ExceptionTranslationFilter can translate it",
-                    cause.getClass().getName());
+        if (shouldDeferToOuterFilter(cause, deferOuterFilterPackages)) {
+            log.debug("Deferring {} so an outer translator can handle it", cause.getClass().getName());
             rethrow(originalToRethrow);
-            return; // unreachable
+            return;
         }
-        // 2. Response already committed: we can't write a new body. Re-raise.
         if (response.isCommitted()) {
             log.warn("Response already committed when {} escaped; re-raising for container error handling",
                     cause.getClass().getName());
             rethrow(originalToRethrow);
-            return; // unreachable
+            return;
         }
-        // 3. Truly unhandled — render the standard 500 body so the client gets a real response.
         log.error("Unhandled exception bubbled to outer captor filter — rendering 500. Exception type: {}",
                 cause.getClass().getName(), cause);
         writeErrorBody(request, response, cause);
     }
 
     /**
-     * Walks the cause chain looking for any Spring Security exception type. Uses an
-     * {@code isInstance} check against the loaded {@code AccessDeniedException} /
-     * {@code AuthenticationException} classes (covers all current and future subclasses) and
-     * a package-prefix fallback (covers any other security exception that doesn't extend those
-     * two roots — e.g. internal token-validation exceptions in oauth2 resource-server).
+     * Walks the exception's cause chain looking for any frame whose class name starts with one
+     * of the configured defer-prefixes. Depth-limited and self-reference-safe. Public so it can
+     * be used in tests / custom filters.
      */
-    public static boolean shouldDeferToSecurityFilter(Throwable t) {
+    public static boolean shouldDeferToOuterFilter(Throwable t, List<String> packagePrefixes) {
+        if (packagePrefixes == null || packagePrefixes.isEmpty()) return false;
         Throwable cursor = t;
         int depth = 0;
         while (cursor != null && depth++ < 16) {
-            if (ACCESS_DENIED_CLASS != null && ACCESS_DENIED_CLASS.isInstance(cursor)) return true;
-            if (AUTHENTICATION_EXCEPTION_CLASS != null && AUTHENTICATION_EXCEPTION_CLASS.isInstance(cursor)) return true;
-            if (cursor.getClass().getName().startsWith(SECURITY_PACKAGE_PREFIX)) return true;
+            String className = cursor.getClass().getName();
+            for (String prefix : packagePrefixes) {
+                if (prefix != null && !prefix.isEmpty() && className.startsWith(prefix)) {
+                    return true;
+                }
+            }
             Throwable next = cursor.getCause();
-            if (next == cursor) break; // self-cause guard
+            if (next == cursor) break;
             cursor = next;
         }
         return false;

spring-web-captor/src/test/java/com/acme/security/CustomDenied.java

@@ -0,0 +1,12 @@
+package com.acme.security;
+
+/**
+ * Test fixture only — pretends to be a security exception from a custom framework outside the
+ * Spring Security namespace, used to verify {@code web-captor.defer-outer-filter-packages} can
+ * be extended to cover arbitrary packages without library code changes.
+ */
+public class CustomDenied extends RuntimeException {
+    public CustomDenied(String msg) {
+        super(msg);
+    }
+}