feat: Add per-request after-hook queue to Request

Author: thced

src/main/java/com/retailsvc/http/Request.java

@@ -2,7 +2,9 @@
 
 import java.net.URLDecoder;
 import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
 import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
@@ -31,6 +33,7 @@ public final class Request {
   private final UnaryOperator<String> headerLookup;
   private final Map<String, Object> principals;
   private Map<String, String> queryParamCache;
+  private final List<Runnable> afterHooks;
 
   /**
    * Builds a {@code Request} from transport-neutral primitives. Adapters call this; handlers
@@ -90,6 +93,32 @@ public Request(
     this.rawQuery = rawQuery;
     this.headerLookup = headerLookup;
     this.principals = Map.copyOf(principals);
+    this.afterHooks = new ArrayList<>();
+  }
+
+  // Package-private: lets withPrincipals(...) thread the after-hook queue through so that
+  // runnables registered on either the original Request or the principals-enriched copy
+  // land in the same backing list.
+  @SuppressWarnings("java:S107")
+  Request(
+      byte[] body,
+      Object parsed,
+      TypeMapper bodyMapper,
+      String operationId,
+      Map<String, String> pathParameters,
+      String rawQuery,
+      UnaryOperator<String> headerLookup,
+      Map<String, Object> principals,
+      List<Runnable> afterHooks) {
+    this.body = body;
+    this.parsed = parsed;
+    this.bodyMapper = bodyMapper;
+    this.operationId = operationId;
+    this.pathParameters = pathParameters;
+    this.rawQuery = rawQuery;
+    this.headerLookup = headerLookup;
+    this.principals = Map.copyOf(principals);
+    this.afterHooks = afterHooks;
   }
 
   public byte[] bytes() {
@@ -214,7 +243,35 @@ public Optional<Object> principal(String schemeName) {
    */
   public Request withPrincipals(Map<String, Object> principals) {
     return new Request(
-        body, parsed, bodyMapper, operationId, pathParameters, rawQuery, headerLookup, principals);
+        body,
+        parsed,
+        bodyMapper,
+        operationId,
+        pathParameters,
+        rawQuery,
+        headerLookup,
+        principals,
+        afterHooks);
+  }
+
+  /**
+   * Queues a {@link Runnable} to execute after the HTTP response has been sent to the client. Runs
+   * on the request thread inside the library's request {@link ScopedValue} binding. Multiple calls
+   * queue FIFO. Exceptions thrown by the runnable are logged at DEBUG and swallowed.
+   *
+   * <p>Calls made after the runner has snapshotted the queue (e.g. from inside a running hook, or
+   * from a leaked {@code Request} reference held past the response) are silently ignored.
+   *
+   * @throws NullPointerException if {@code runnable} is null
+   */
+  public void afterResponse(Runnable runnable) {
+    Objects.requireNonNull(runnable, "runnable must not be null");
+    afterHooks.add(runnable);
+  }
+
+  /** Package-private accessor for the after-hook queue; used by RequestPreparationFilter. */
+  List<Runnable> afterHooks() {
+    return afterHooks;
   }
 
   private static Map<String, String> parseQuery(String query) {

src/test/java/com/retailsvc/http/RequestTest.java

@@ -2,11 +2,14 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.retailsvc.http.internal.DispatchHandler;
 import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.UnaryOperator;
@@ -231,6 +234,47 @@ void withPrincipalsDoesNotShareUnderlyingMap() {
     assertThat(copy.principal("a")).contains("b");
   }
 
+  private static Request newRequest() {
+    return new Request(new byte[0], null, null, "op", Map.of(), null, name -> null);
+  }
+
+  @Test
+  void afterResponseRejectsNull() {
+    Request request = newRequest();
+    assertThrows(NullPointerException.class, () -> request.afterResponse(null));
+  }
+
+  @Test
+  void afterResponseQueuesInOrder() {
+    Request request = newRequest();
+    List<String> log = new ArrayList<>();
+    request.afterResponse(() -> log.add("first"));
+    request.afterResponse(() -> log.add("second"));
+
+    for (Runnable r : request.afterHooks()) {
+      r.run();
+    }
+
+    assertThat(log).containsExactly("first", "second");
+  }
+
+  @Test
+  void withPrincipalsSharesAfterHookQueue() {
+    Request original = newRequest();
+    List<String> log = new ArrayList<>();
+    original.afterResponse(() -> log.add("from-original"));
+
+    Request enriched = original.withPrincipals(Map.of("scheme", "principal"));
+    enriched.afterResponse(() -> log.add("from-enriched"));
+
+    for (Runnable r : original.afterHooks()) {
+      r.run();
+    }
+
+    assertThat(log).containsExactly("from-original", "from-enriched");
+    assertThat(original.afterHooks()).isSameAs(enriched.afterHooks());
+  }
+
   @Test
   void headerReturnsOptionalAndBlankIsAbsent() {
     Request req =