- add asciidoc

Author: jknack

docs/asciidoc/gRPC.adoc

@@ -0,0 +1,108 @@
+== gRPC
+
+The `jooby-grpc` module provides first-class, native support for https://grpc.io/[gRPC].
+
+Unlike traditional setups that require spinning up a separate gRPC server on a different port (often forcing a specific transport like Netty), this module embeds the `grpc-java` engine directly into Jooby.
+
+By using a custom native bridge, it allows you to run strictly-typed gRPC services alongside your standard REST API routes on the **exact same port**. It bypasses the standard HTTP/1.1 pipeline in favor of a highly optimized, native interceptor tailored for HTTP/2 multiplexing, reactive backpressure, and zero-copy byte framing. It works natively across Undertow, Netty, and Jetty.
+
+=== Dependency
+
+[source, xml, role="primary"]
+.Maven
+----
+<dependency>
+  <groupId>io.jooby</groupId>
+  <artifactId>jooby-grpc</artifactId>
+  <version>${jooby.version}</version>
+</dependency>
+----
+
+[source, gradle, role="secondary"]
+.Gradle
+----
+implementation 'io.jooby:jooby-grpc:${jooby.version}'
+----
+
+=== Usage
+
+gRPC strictly requires HTTP/2. Before installing the module, ensure your application is configured to use a supported server with HTTP/2 enabled.
+
+[source, java]
+----
+import io.jooby.Jooby;
+import io.jooby.ServerOptions;
+import io.jooby.grpc.GrpcModule;
+
+public class App extends Jooby {
+  {
+    setServerOptions(new ServerOptions().setHttp2(true)); // <1>
+
+    install(new GrpcModule( // <2>
+        new GreeterService()
+    ));
+
+    get("/api/health", ctx -> "OK"); // <3>
+  }
+
+  public static void main(String[] args) {
+    runApp(args, App::new);
+  }
+}
+----
+<1> Enable HTTP/2 on your server.
+<2> Install the module and explicitly register your services.
+<3> Standard REST routes still work on the exact same port!
+
+=== Dependency Injection
+
+If your gRPC services require external dependencies (like database repositories), you can register the service classes instead of pre-instantiated objects. The module will automatically provision them using your active Dependency Injection framework (e.g., Guice, Spring).
+
+[source, java]
+----
+import io.jooby.Jooby;
+import io.jooby.di.GuiceModule;
+import io.jooby.grpc.GrpcModule;
+
+public class App extends Jooby {
+  {
+    install(new GuiceModule());
+
+    install(new GrpcModule(
+        GreeterService.class // <1>
+    ));
+  }
+}
+----
+<1> Pass the class references. The DI framework will instantiate them.
+
+WARNING: gRPC services are registered as **Singletons**. Ensure your service implementations are thread-safe and do not hold request-scoped state in instance variables. Heavy blocking operations will safely run on background workers, protecting the native server's I/O event loops.
+
+=== Server Reflection
+
+If you want to use tools like `grpcurl` or Postman to interact with your services without providing the `.proto` files, you can easily enable gRPC Server Reflection.
+
+Include the `grpc-services` dependency in your build, and register the v1 reflection service alongside your own:
+
+[source, java]
+----
+import io.grpc.protobuf.services.ProtoReflectionServiceV1;
+
+public class App extends Jooby {
+  {
+    install(new GrpcModule(
+        new GreeterService(),
+        ProtoReflectionServiceV1.newInstance() // <1>
+    ));
+  }
+}
+----
+<1> Enables the modern `v1` reflection protocol for maximum compatibility with gRPC clients.
+
+=== Routing & Fallbacks
+
+The gRPC module intercepts requests natively before they reach Jooby's standard router.
+
+If a client attempts to call a gRPC method that does not exist, the request gracefully falls through to the standard Jooby router, returning a native `404 Not Found` (which gRPC clients will automatically translate to a Status `12 UNIMPLEMENTED`).
+
+If you misconfigure your server (e.g., attempting to run gRPC over HTTP/1.1), the fallback route will catch the request and throw an `IllegalStateException` to help you identify the missing configuration immediately.

jooby/src/main/java/io/jooby/GrpcProcessor.java

@@ -13,22 +13,21 @@
 /**
  * Core Service Provider Interface (SPI) for the gRPC extension.
  *
- * <p>This processor acts as the bridge between the native HTTP/2 web servers (Undertow, Netty,
- * Jetty) and the embedded gRPC engine. It is designed to intercept and process gRPC exchanges at
- * the lowest possible network level, completely bypassing Jooby's standard HTTP/1.1 routing
- * pipeline. This architecture ensures strict HTTP/2 specification compliance, zero-copy buffering,
- * and reactive backpressure.
+ * <p>This processor acts as the bridge between the native HTTP/2 web servers and the embedded gRPC
+ * engine. It is designed to intercept and process gRPC exchanges at the lowest possible network
+ * level, completely bypassing Jooby's standard HTTP/1.1 routing pipeline. This architecture ensures
+ * strict HTTP/2 specification compliance, zero-copy buffering, and reactive backpressure.
  */
 public interface GrpcProcessor {
 
   /**
    * Checks if the given URI path exactly matches a registered gRPC method.
    *
-   * <p>Native server interceptors (Undertow, Netty, Jetty) use this method as a lightweight,
-   * fail-fast guard. If this returns {@code true}, the server will hijack the request and upgrade
-   * it to a native gRPC stream. If {@code false}, the request safely falls through to the standard
-   * Jooby router (typically resulting in a standard HTTP 404 Not Found, which gRPC clients
-   * gracefully translate to Status 12 UNIMPLEMENTED).
+   * <p>Native server interceptors use this method as a lightweight, fail-fast guard. If this
+   * returns {@code true}, the server will hijack the request and upgrade it to a native gRPC
+   * stream. If {@code false}, the request safely falls through to the standard Jooby router
+   * (typically resulting in a standard HTTP 404 Not Found, which gRPC clients gracefully translate
+   * to Status 12 UNIMPLEMENTED).
    *
    * @param path The incoming request path (e.g., {@code /fully.qualified.Service/MethodName}).
    * @return {@code true} if the path is mapped to an active gRPC service; {@code false} otherwise.

jooby/src/main/java/io/jooby/ServerOptions.java

@@ -290,7 +290,7 @@ public int getPort() {
    * @return True when SSL is enabled. Either bc the secure port, httpsOnly or SSL options are set.
    */
   public boolean isSSLEnabled() {
-    return securePort != null || ssl != null || httpsOnly;
+    return securePort != null || ssl != null || http2 == Boolean.TRUE || httpsOnly;
   }
 
   /**

modules/jooby-grpc/src/main/java/io/jooby/grpc/GrpcModule.java

@@ -23,12 +23,12 @@
  * <p>This module allows you to run strictly-typed gRPC services alongside standard Jooby HTTP
  * routes on the exact same port. It completely bypasses standard HTTP/1.1 pipelines in favor of a
  * highly optimized, reactive, native interceptor tailored for HTTP/2 multiplexing and trailing
- * headers. *
+ * headers.
  *
  * <h3>Usage</h3>
  *
  * <p>gRPC requires HTTP/2. Ensure your Jooby application is configured to use a supported server
- * (Undertow, Netty, or Jetty) with HTTP/2 enabled. *
+ * with HTTP/2 enabled.
  *
  * <pre>{@code
  * import io.jooby.Jooby;
@@ -43,13 +43,11 @@
  * }
  * }</pre>
  *
- * *
- *
  * <h3>Dependency Injection</h3>
  *
  * <p>If your gRPC services require external dependencies (like repositories or configuration), you
  * can register the service classes instead of instances. The module will automatically provision
- * them using Jooby's DI registry (e.g., Guice, Spring) during the application startup phase. *
+ * them using Jooby's DI registry (e.g., Guice, Spring) during the application startup phase.
  *
  * <pre>{@code
  * public class App extends Jooby {
@@ -65,7 +63,7 @@
  *
  * <p><strong>Note:</strong> gRPC services are inherently registered as Singletons. Ensure your
  * service implementations are thread-safe and do not hold request-scoped state in instance
- * variables. *
+ * variables.
  *
  * <h3>Logging</h3>
  *
@@ -159,8 +157,9 @@ public void install(@NonNull Jooby app) throws Exception {
 
   /**
    * Internal helper to register a service with the gRPC builder, extract its method descriptors,
-   * and map a fail-fast route in the Jooby router. * @param app The target Jooby application.
+   * and map a fail-fast route in the Jooby router.
    *
+   * @param app The target Jooby application.
    * @param server The in-process server builder.
    * @param registry The method descriptor registry.
    * @param service The provisioned gRPC service to bind.
@@ -183,11 +182,11 @@ private static void bindService(
           routePath,
           ctx -> {
             throw new IllegalStateException(
-                "gRPC request reached the standard HTTP router for path: "
+                "gRPC request reached the standard HTTP router for: "
                     + routePath
                     + ". "
                     + "This means the native gRPC server interceptor was bypassed. "
-                    + "Ensure you are running Jetty, Netty, or Undertow with HTTP/2 enabled, "
+                    + "Ensure you are running with HTTP/2 enabled, "
                     + "and that the GrpcProcessor SPI is correctly loaded.");
           });
     }

tests/src/test/java/io/jooby/test/Http2Test.java

@@ -42,7 +42,7 @@ public class Http2Test {
   @ServerTest
   public void h2body(ServerTestRunner runner) {
     runner
-        .options(new ServerOptions().setHttp2(true).setSecurePort(8443))
+        .options(new ServerOptions().setHttp2(true))
         .define(
             app -> {
               app.install(new JacksonModule());