gRPC: javadoc for major/public components

Author: jknack

jooby/src/main/java/io/jooby/GrpcExchange.java

@@ -11,23 +11,73 @@
 
 import edu.umd.cs.findbugs.annotations.Nullable;
 
-/** Server-agnostic abstraction for HTTP/2 trailing-header exchanges. */
+/**
+ * Server-agnostic abstraction for a native HTTP/2 gRPC exchange.
+ *
+ * <p>This interface bridges the gap between the underlying web server (Undertow, Netty, or Jetty)
+ * and the reactive gRPC processor. Because gRPC heavily relies on HTTP/2 multiplexing, asynchronous
+ * I/O, and trailing headers (trailers) to communicate status codes, standard HTTP/1.1 context
+ * abstractions are insufficient.
+ *
+ * <p>Native server interceptors wrap their respective request/response objects into this interface,
+ * allowing the {@link GrpcProcessor} to read headers, push zero-copy byte frames, and finalize the
+ * stream with standard gRPC trailers without knowing which server engine is actually running.
+ */
 public interface GrpcExchange {
 
+  /**
+   * Retrieves the requested URI path.
+   *
+   * <p>In gRPC, this dictates the routing and strictly follows the pattern: {@code
+   * /Fully.Qualified.ServiceName/MethodName}.
+   *
+   * @return The exact path of the incoming HTTP/2 request.
+   */
   String getRequestPath();
 
+  /**
+   * Retrieves the value of the specified HTTP request header.
+   *
+   * @param name The name of the header (case-insensitive).
+   * @return The header value, or {@code null} if the header is not present.
+   */
   @Nullable String getHeader(String name);
 
+  /**
+   * Retrieves all HTTP request headers.
+   *
+   * @return A map containing all headers provided by the client.
+   */
   Map<String, String> getHeaders();
 
-  /** Write framed bytes to the underlying non-blocking socket. */
+  /**
+   * Writes a gRPC-framed byte payload to the underlying non-blocking socket.
+   *
+   * <p>This method must push the buffer to the native network layer without blocking the invoking
+   * thread (which is typically a background gRPC worker). The implementation is responsible for
+   * translating the ByteBuffer into the server's native data format and flushing it over the
+   * network.
+   *
+   * @param payload The properly framed 5-byte-prefixed gRPC payload to send.
+   * @param onFailure A callback invoked immediately if the asynchronous network write fails (e.g.,
+   *     if the client abruptly disconnects or the channel is closed).
+   */
   void send(ByteBuffer payload, Consumer<Throwable> onFailure);
 
   /**
-   * Closes the HTTP/2 stream with trailing headers.
+   * Closes the HTTP/2 stream by appending the mandatory gRPC trailing headers.
+   *
+   * <p>In the gRPC specification, a successful response or an application-level error is
+   * communicated not by standard HTTP status codes (which are always 200 OK), but by appending
+   * HTTP/2 trailers ({@code grpc-status} and {@code grpc-message}) at the very end of the stream.
+   *
+   * <p>Calling this method informs the native server to write those trailing headers and formally
+   * close the bidirectional stream.
    *
-   * @param statusCode The gRPC status code (e.g., 0 for OK, 12 for UNIMPLEMENTED).
-   * @param description Optional status message.
+   * @param statusCode The gRPC integer status code (e.g., {@code 0} for OK, {@code 12} for
+   *     UNIMPLEMENTED, {@code 4} for DEADLINE_EXCEEDED).
+   * @param description An optional, human-readable status message detailing the result or error.
+   *     May be {@code null}.
    */
-  void close(int statusCode, String description);
+  void close(int statusCode, @Nullable String description);
 }

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

@@ -10,15 +10,43 @@
 
 import edu.umd.cs.findbugs.annotations.NonNull;
 
-/** Intercepts and processes gRPC exchanges. */
+/**
+ * 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.
+ */
 public interface GrpcProcessor {
 
-  /** Checks if the given URI path exactly matches a registered gRPC method. */
+  /**
+   * 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).
+   *
+   * @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.
+   */
   boolean isGrpcMethod(String path);
 
   /**
-   * @return A subscriber that the server will feed ByteBuffer chunks into, or null if the exchange
-   *     was rejected/unimplemented.
+   * Initiates the reactive gRPC pipeline for an incoming HTTP/2 request.
+   *
+   * <p>When a valid gRPC request is intercepted, the native server wraps the underlying network
+   * connection into a {@link GrpcExchange} and passes it to this method. The processor uses this
+   * exchange to asynchronously send response headers, payload byte frames, and HTTP/2 trailers.
+   *
+   * @param exchange The native server exchange representing the bidirectional HTTP/2 stream.
+   * @return A reactive {@link Flow.Subscriber} that the native server must feed incoming request
+   *     payload {@link ByteBuffer} chunks into. Returns {@code null} if the exchange was rejected.
+   * @throws IllegalStateException If an unregistered path bypasses the {@link
+   *     #isGrpcMethod(String)} guard.
    */
   Flow.Subscriber<ByteBuffer> process(@NonNull GrpcExchange exchange);
 }

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

@@ -17,6 +17,61 @@
 import io.jooby.*;
 import io.jooby.internal.grpc.DefaultGrpcProcessor;
 
+/**
+ * Native gRPC extension for Jooby. *
+ *
+ * <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. *
+ *
+ * <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. *
+ *
+ * <pre>{@code
+ * import io.jooby.Jooby;
+ * import io.jooby.ServerOptions;
+ * import io.jooby.grpc.GrpcModule;
+ * * public class App extends Jooby {
+ * {
+ * setServerOptions(new ServerOptions().setHttp2(true).setSecurePort(8443));
+ * * // Install the extension and register your services
+ * install(new GrpcModule(new GreeterService()));
+ * }
+ * }
+ * }</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. *
+ *
+ * <pre>{@code
+ * public class App extends Jooby {
+ * {
+ * install(new GuiceModule());
+ * * // Pass the class reference. Guice will instantiate it!
+ * install(new GrpcModule(GreeterService.class));
+ * }
+ * }
+ * }</pre>
+ *
+ * *
+ *
+ * <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. *
+ *
+ * <h3>Logging</h3>
+ *
+ * <p>gRPC internally uses {@code java.util.logging}. This module automatically installs the {@link
+ * SLF4JBridgeHandler} to redirect all internal gRPC logs to your configured SLF4J backend.
+ */
 public class GrpcModule implements Extension {
   private final List<BindableService> services = new ArrayList<>();
   private final List<Class<? extends BindableService>> serviceClasses = new ArrayList<>();
@@ -28,21 +83,45 @@ public class GrpcModule implements Extension {
     SLF4JBridgeHandler.install();
   }
 
+  /**
+   * Creates a new gRPC module with pre-instantiated service objects. * @param services One or more
+   * fully instantiated gRPC services.
+   */
   public GrpcModule(BindableService... services) {
     this.services.addAll(Arrays.asList(services));
   }
 
+  /**
+   * Creates a new gRPC module with service classes to be provisioned via Dependency Injection.
+   * * @param serviceClasses One or more gRPC service classes to be resolved from the Jooby
+   * registry.
+   */
   @SafeVarargs
   public GrpcModule(Class<? extends BindableService>... serviceClasses) {
     bind(serviceClasses);
   }
 
+  /**
+   * Registers additional gRPC service classes to be provisioned via Dependency Injection. * @param
+   * serviceClasses One or more gRPC service classes to be resolved from the Jooby registry.
+   *
+   * @return This module for chaining.
+   */
   @SafeVarargs
   public final GrpcModule bind(Class<? extends BindableService>... serviceClasses) {
     this.serviceClasses.addAll(List.of(serviceClasses));
     return this;
   }
 
+  /**
+   * Installs the gRPC extension into the Jooby application. *
+   *
+   * <p>This method sets up the {@link GrpcProcessor} SPI, registers native fallback routes, and
+   * defers DI resolution and the starting of the embedded in-process gRPC server to the {@code
+   * onStarting} lifecycle hook. * @param app The target Jooby application.
+   *
+   * @throws Exception If an error occurs during installation.
+   */
   @Override
   public void install(@NonNull Jooby app) throws Exception {
     var serverName = app.getName();
@@ -78,6 +157,14 @@ 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.
+   *
+   * @param server The in-process server builder.
+   * @param registry The method descriptor registry.
+   * @param service The provisioned gRPC service to bind.
+   */
   private static void bindService(
       Jooby app,
       InProcessServerBuilder server,
@@ -89,7 +176,9 @@ private static void bindService(
       String methodFullName = descriptor.getFullMethodName();
       registry.put(methodFullName, descriptor);
       String routePath = "/" + methodFullName;
-      //
+
+      // Map a fallback route. If a request hits this, it means the native SPI interceptor
+      // failed to upgrade the request, typically due to a missing HTTP/2 configuration.
       app.post(
           routePath,
           ctx -> {