Fix tRPC reactive type leaks and support all HTTP mutations

This update hardens the TypeScript generation pipeline to prevent
internal JVM and reactive wrapper types from leaking into the client
definitions, and expands tRPC mutation support to cover all standard
state-changing HTTP verbs.

Key changes:
* TrpcGenerator: Fixed a bug where `CompletableFuture`, `Mono`, `Single`,
  and other async wrappers were being emitted in the `trpc.d.ts` output.
  Implemented a deep recursive unwrapping mechanism to extract the true
  underlying DTOs from complex generic, wildcard, and array signatures.
* TrpcGenerator: Added a Jackson "firewall" to the typescript-generator
  settings, explicitly mapping all known async wrappers to `any` to
  prevent indirect discovery via reflection.
* TrpcGenerator: Dynamically extracts generic type parameters (e.g.,
  `Future<V>`) via reflection to satisfy typescript-generator's strict
  custom mapping validation, while safely ignoring wrappers not present
  on the compilation classpath.
* TrpcGenerator: Made the `AppRouter` output 100% deterministic to
  prevent test flakiness. Procedures are now grouped by namespace,
  visually separated into `// queries` and `// mutations`, and sorted
  alphabetically.
* MvcRoute (APT) & TrpcGenerator: Expanded mutation detection. Methods
  annotated with base `@Trpc` alongside `@PUT`, `@PATCH`, or `@DELETE`
  are now correctly categorized as mutations in the TypeScript router
  and mapped to HTTP POST proxy routes by the Jooby annotation processor.

Author: jknack

modules/jooby-apt/src/main/java/io/jooby/internal/apt/MvcRoute.java

@@ -1111,7 +1111,12 @@ private HttpMethod trpcMethod(Element element) {
       if (HttpMethod.GET.matches(element)) {
         return HttpMethod.GET;
       }
-      if (HttpMethod.POST.matches(element)) {
+
+      // Map all state-changing HTTP annotations to a tRPC POST mutation
+      if (HttpMethod.POST.matches(element)
+          || HttpMethod.PUT.matches(element)
+          || HttpMethod.PATCH.matches(element)
+          || HttpMethod.DELETE.matches(element)) {
         return HttpMethod.POST;
       }
 
@@ -1121,8 +1126,9 @@ private HttpMethod trpcMethod(Element element) {
               + element.getSimpleName()
               + "() in "
               + element.getEnclosingElement().getSimpleName()
-              + " is annotated with @Trpc but lacks @GET or @POST. Please annotate the method with"
-              + " @Trpc.Query, @Trpc.Mutation, or combine @Trpc with @GET or @POST.");
+              + " is annotated with @Trpc but lacks a valid HTTP method annotation. Please annotate"
+              + " the method with @Trpc.Query, @Trpc.Mutation, or combine @Trpc with @GET, @POST,"
+              + " @PUT, @PATCH, or @DELETE.");
     }
     return null;
   }

modules/jooby-trpc/pom.xml

@@ -81,6 +81,11 @@
       <artifactId>mockito-core</artifactId>
       <scope>test</scope>
     </dependency>
+    <dependency>
+      <groupId>io.projectreactor</groupId>
+      <artifactId>reactor-core</artifactId>
+      <version>3.8.3</version>
+    </dependency>
     <dependency>
       <groupId>org.assertj</groupId>
       <artifactId>assertj-core</artifactId>

modules/jooby-trpc/src/main/java/io/jooby/trpc/TrpcGenerator.java

@@ -52,6 +52,32 @@
  */
 public class TrpcGenerator {
 
+  private static final Set<String> WRAPPERS =
+      Set.of(
+          // Protocol Envelope
+          "io.jooby.trpc.TrpcResponse",
+          // JDK Async
+          "java.util.concurrent.CompletableFuture",
+          "java.util.concurrent.CompletionStage",
+          "java.util.concurrent.Future",
+          // Reactor
+          "reactor.core.publisher.Mono",
+          "reactor.core.publisher.Flux",
+          // Mutiny
+          "io.smallrye.mutiny.Uni",
+          "io.smallrye.mutiny.Multi",
+          // RxJava 2 & 3
+          "io.reactivex.Single",
+          "io.reactivex.Maybe",
+          "io.reactivex.Observable",
+          "io.reactivex.Flowable",
+          "io.reactivex.Completable",
+          "io.reactivex.rxjava3.core.Single",
+          "io.reactivex.rxjava3.core.Maybe",
+          "io.reactivex.rxjava3.core.Observable",
+          "io.reactivex.rxjava3.core.Flowable",
+          "io.reactivex.rxjava3.core.Completable");
+
   private final Logger log = LoggerFactory.getLogger(getClass());
 
   private ClassLoader classLoader = getClass().getClassLoader();
@@ -103,9 +129,9 @@ public void generate() throws IOException {
         if (!includeMethod && expandLookup) includeMethod = hasWebAnnotation(method);
 
         if (includeMethod) {
-          typesToGenerate.add(method.getGenericReturnType());
+          addTypeToGenerate(typesToGenerate, method.getGenericReturnType());
           for (var param : method.getGenericParameterTypes()) {
-            typesToGenerate.add(param);
+            addTypeToGenerate(typesToGenerate, param);
           }
         }
       }
@@ -125,6 +151,31 @@ public void generate() throws IOException {
     // 2. Generate standard interfaces (DTOs only)
     if (!typesToGenerate.isEmpty()) {
       TypeScriptGenerator.setLogger(asSlf4j(log));
+
+      /// FIREWALL: Force the generator to ignore all reactive wrappers if discovered indirectly.
+      // typescript-generator strictly demands exact generic signatures (e.g. Future<V>).
+      // We dynamically append the type variables using reflection to satisfy its parser.
+      for (String wrapper : WRAPPERS) {
+        try {
+          Class<?> clazz = Class.forName(wrapper, false, classLoader);
+          StringBuilder key = new StringBuilder(wrapper);
+          var typeParams = clazz.getTypeParameters();
+
+          if (typeParams.length > 0) {
+            key.append("<");
+            for (int i = 0; i < typeParams.length; i++) {
+              if (i > 0) key.append(", ");
+              key.append(typeParams[i].getName());
+            }
+            key.append(">");
+          }
+
+          settings.customTypeMappings.put(key.toString(), "any");
+        } catch (ClassNotFoundException | NoClassDefFoundError ignored) {
+          // Class not on classpath, safe to ignore
+        }
+      }
+
       var generator = new TypeScriptGenerator(settings);
       var input = Input.from(typesToGenerate.toArray(new Type[0]));
       generator.generateTypeScript(input, Output.to(finalOutput.toFile()));
@@ -155,6 +206,45 @@ protected void write(Level level, String message) {
     };
   }
 
+  private void addTypeToGenerate(Set<Type> types, Type type) {
+    if (type == void.class || type == Void.class) return;
+
+    if (type instanceof ParameterizedType pt) {
+      var rawName = pt.getRawType().getTypeName();
+
+      // Unwrap async and protocol wrapper types
+      if (WRAPPERS.contains(rawName) && pt.getActualTypeArguments().length > 0) {
+        addTypeToGenerate(types, pt.getActualTypeArguments()[0]);
+        return;
+      }
+
+      // Decompose standard generic types to ensure inner DTOs are discovered safely
+      addTypeToGenerate(types, pt.getRawType());
+      for (Type arg : pt.getActualTypeArguments()) {
+        addTypeToGenerate(types, arg);
+      }
+      return;
+    } else if (type instanceof Class<?> clazz) {
+      // Ignore bare async types (like RxJava Completable) that signify void
+      if (WRAPPERS.contains(clazz.getName())) return;
+
+      if (clazz.isArray()) {
+        addTypeToGenerate(types, clazz.getComponentType());
+        return;
+      }
+    } else if (type instanceof java.lang.reflect.WildcardType wt) {
+      for (Type bound : wt.getUpperBounds()) {
+        if (bound != Object.class) addTypeToGenerate(types, bound);
+      }
+      return;
+    } else if (type instanceof java.lang.reflect.GenericArrayType gat) {
+      addTypeToGenerate(types, gat.getGenericComponentType());
+      return;
+    }
+
+    types.add(type);
+  }
+
   /**
    * Constructs and appends the tRPC {@code AppRouter} mapping to the bottom of the generated file.
    *
@@ -168,46 +258,71 @@ private void appendTrpcRouter(Path finalOutput, Set<Class<?>> controllers) throw
     ts.append("\n// --- tRPC Router Mapping ---\n\n");
     ts.append("export type AppRouter = {\n");
 
+    // 1. Group by namespace using a TreeMap to guarantee deterministic alphabetical order
+    Map<String, List<Method>> namespaces = new java.util.TreeMap<>();
+
     for (var controller : controllers) {
       var namespace = extractNamespace(controller);
-      String indent = "  "; // Default indent for root methods
+      String key = namespace == null ? "" : namespace;
 
-      if (namespace != null) {
-        ts.append("  ").append(namespace).append(": {\n");
-        indent = "    "; // Increase indent for nested methods
-      }
+      namespaces.computeIfAbsent(key, k -> new ArrayList<>());
 
       for (var method : controller.getDeclaredMethods()) {
         boolean includeMethod = isTrpcAnnotated(method);
         if (!includeMethod && expandLookup) includeMethod = hasWebAnnotation(method);
 
         if (includeMethod) {
-          var params = method.getGenericParameterTypes();
-          String tsInput = "void";
-
-          // Seamless tRPC: single arguments are raw, multiple arguments are packed in a tuple
-          if (params.length == 1) {
-            tsInput = resolveTsType(params[0]);
-          } else if (params.length > 1) {
-            var tuple = new ArrayList<String>();
-            for (var p : params) tuple.add(resolveTsType(p));
-            tsInput = "[" + String.join(", ", tuple) + "]";
-          }
+          namespaces.get(key).add(method);
+        }
+      }
+    }
+
+    // 2. Generate the TypeScript output
+    for (var entry : namespaces.entrySet()) {
+      String namespace = entry.getKey();
+      List<Method> methods = entry.getValue();
 
-          String tsOutput = resolveTsType(method.getGenericReturnType());
-          String procedureName = getProcedureName(method);
+      if (methods.isEmpty()) continue;
 
-          ts.append(indent)
-              .append(procedureName)
-              .append(": { input: ")
-              .append(tsInput)
-              .append("; output: ")
-              .append(tsOutput)
-              .append(" };\n");
+      String indent = "  ";
+      if (!namespace.isEmpty()) {
+        ts.append("  ").append(namespace).append(": {\n");
+        indent = "    ";
+      }
+
+      // Separate into queries and mutations for deterministic grouping
+      List<Method> queries = new ArrayList<>();
+      List<Method> mutations = new ArrayList<>();
+
+      for (Method m : methods) {
+        if (isMutation(m)) {
+          mutations.add(m);
+        } else {
+          queries.add(m);
+        }
+      }
+
+      // Sort alphabetically by procedure name to prevent reflection-order test flakiness
+      java.util.Comparator<Method> byName = java.util.Comparator.comparing(this::getProcedureName);
+      queries.sort(byName);
+      mutations.sort(byName);
+
+      if (!queries.isEmpty()) {
+        ts.append(indent).append("// queries\n");
+        for (Method method : queries) {
+          appendProcedure(ts, indent, method);
+        }
+      }
+
+      if (!mutations.isEmpty()) {
+        if (!queries.isEmpty()) ts.append("\n"); // Add a blank line between groups if both exist
+        ts.append(indent).append("// mutations\n");
+        for (Method method : mutations) {
+          appendProcedure(ts, indent, method);
         }
       }
 
-      if (namespace != null) {
+      if (!namespace.isEmpty()) {
         ts.append("  };\n");
       }
     }
@@ -216,6 +331,61 @@ private void appendTrpcRouter(Path finalOutput, Set<Class<?>> controllers) throw
     Files.writeString(finalOutput, ts.toString(), StandardOpenOption.APPEND);
   }
 
+  private void appendProcedure(StringBuilder ts, String indent, Method method) {
+    var params = method.getGenericParameterTypes();
+    String tsInput = "void";
+
+    // Seamless tRPC: single arguments are raw, multiple arguments are packed in a tuple
+    if (params.length == 1) {
+      tsInput = resolveTsType(params[0]);
+    } else if (params.length > 1) {
+      var tuple = new ArrayList<String>();
+      for (var p : params) tuple.add(resolveTsType(p));
+      tsInput = "[" + String.join(", ", tuple) + "]";
+    }
+
+    String tsOutput = resolveTsType(method.getGenericReturnType());
+    String procedureName = getProcedureName(method);
+
+    ts.append(indent)
+        .append(procedureName)
+        .append(": { input: ")
+        .append(tsInput)
+        .append("; ")
+        .append("output: ")
+        .append(tsOutput)
+        .append(" };\n");
+  }
+
+  private boolean isMutation(Method method) {
+    // 1. Explicit tRPC mutation annotation
+    if (getAnnotation(method, "io.jooby.annotation.Trpc$Mutation") != null) {
+      return true;
+    }
+    // 2. Explicit tRPC query annotation
+    if (getAnnotation(method, "io.jooby.annotation.Trpc$Query") != null) {
+      return false;
+    }
+
+    // 3. Base @Trpc combined with standard HTTP mutation annotations
+    String[] httpMutations = {
+      "io.jooby.annotation.POST", "io.jooby.annotation.PUT",
+      "io.jooby.annotation.PATCH", "io.jooby.annotation.DELETE",
+      "jakarta.ws.rs.POST", "jakarta.ws.rs.PUT",
+      "jakarta.ws.rs.PATCH", "jakarta.ws.rs.DELETE",
+      "javax.ws.rs.POST", "javax.ws.rs.PUT",
+      "javax.ws.rs.PATCH", "javax.ws.rs.DELETE"
+    };
+
+    for (String ann : httpMutations) {
+      if (getAnnotation(method, ann) != null) {
+        return true;
+      }
+    }
+
+    return false; // Default to query
+  }
+
   /**
    * Fast, recursive type resolver to map Java types directly to TypeScript signatures. Understands
    * Jooby async types, standard collections, and primitive mappings.
@@ -230,13 +400,8 @@ private String resolveTsType(Type type) {
       var raw = pt.getRawType();
       var rawName = raw.getTypeName();
 
-      // Unwrap async and protocol wrapper types (TrpcResponse, CompletableFuture, Mono, Single,
-      // Future)
-      if (rawName.endsWith("TrpcResponse")
-          || rawName.endsWith("CompletableFuture")
-          || rawName.endsWith("Single")
-          || rawName.endsWith("Mono")
-          || rawName.endsWith("Future")) {
+      // Unwrap async and protocol wrapper types
+      if (WRAPPERS.contains(rawName) && pt.getActualTypeArguments().length > 0) {
         return resolveTsType(pt.getActualTypeArguments()[0]);
       }
 
@@ -259,13 +424,27 @@ private String resolveTsType(Type type) {
       }
     }
 
+    if (type instanceof java.lang.reflect.WildcardType wt) {
+      if (wt.getUpperBounds().length > 0 && wt.getUpperBounds()[0] != Object.class) {
+        return resolveTsType(wt.getUpperBounds()[0]);
+      }
+      return "any";
+    }
+
+    if (type instanceof java.lang.reflect.GenericArrayType gat) {
+      return resolveTsType(gat.getGenericComponentType()) + "[]";
+    }
+
     if (type instanceof Class<?> clazz) {
       if (clazz.isArray()) {
         if (clazz.getComponentType() == byte.class)
           return "string"; // Common byte[] to base64 string
         return resolveTsType(clazz.getComponentType()) + "[]";
       }
 
+      // Handle bare async types (like RxJava Completable) as void returns
+      if (WRAPPERS.contains(clazz.getName())) return "void";
+
       if (clazz == String.class
           || clazz == char.class
           || clazz == Character.class

modules/jooby-trpc/src/test/java/io/jooby/trpc/i3863/C3863.java

@@ -5,10 +5,10 @@
  */
 package io.jooby.trpc.i3863;
 
-import io.jooby.annotation.GET;
-import io.jooby.annotation.POST;
-import io.jooby.annotation.Path;
-import io.jooby.annotation.Trpc;
+import java.util.concurrent.CompletableFuture;
+
+import io.jooby.annotation.*;
+import reactor.core.publisher.Mono;
 
 @Path("/users")
 @Trpc("users") // Custom namespace
@@ -26,6 +26,17 @@ public U3863 createUser(U3863 user) {
     return user;
   }
 
+  @PUT
+  @Trpc
+  public CompletableFuture<U3863> createFuture(U3863 user) {
+    return CompletableFuture.completedFuture(user);
+  }
+
+  @Trpc.Mutation
+  public Mono<U3863> createMono(U3863 user) {
+    return Mono.just(user);
+  }
+
   @GET("/internal")
   public String internalEndpoint() {
     return "This should not be exposed to tRPC";