You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/asciidoc/modules/gRPC.adoc
+27-59Lines changed: 27 additions & 59 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,30 +1,17 @@
1
-
====gRPC
1
+
== gRPC
2
2
3
3
The `jooby-grpc` module provides first-class, native support for https://grpc.io/[gRPC].
4
4
5
5
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.
6
6
7
7
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.
8
8
9
-
=====Usage
9
+
=== Usage
10
10
11
11
gRPC strictly requires HTTP/2. Before installing the module, ensure your application is configured to use a supported server with HTTP/2 enabled.
<2> Install the module and explicitly register your services.
69
-
<3> Standard REST routes still work on the exact same port!
70
46
71
-
===== Dependency Injection
47
+
=== Dependency Injection
72
48
73
49
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).
<1> Pass the class references. The DI framework will instantiate them.
109
79
110
80
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.
111
81
112
-
===== Server Reflection
82
+
=== Server Reflection
113
83
114
84
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.
To expose a JSON-RPC endpoint, annotate your controller or service with `@JsonRpc`. You can optionally provide a namespace to the annotation, which will prefix all generated method names for that class.
10
15
@@ -50,61 +55,57 @@ The annotation dictates how the protocol methods are named and exposed:
50
55
51
56
**Mixing Annotations:** You can freely mix standard REST annotations (like `@GET`, `@POST`) and `@JsonRpc` on the same class. The APT handles this by generating two entirely separate dispatchers: one standard MVC extension (e.g., `MovieService_`) and one JSON-RPC service (e.g., `MovieServiceRpc_`). They do not interfere with each other, allowing you to expose the exact same business logic over both REST and JSON-RPC simultaneously.
52
57
53
-
===== Registration
58
+
=== Registration
54
59
55
60
Register the generated `JsonRpcService` in your application using the `jsonrpc` method. You must also install a supported JSON engine.
56
61
57
62
.JSON-RPC
58
63
[source,java,role="primary"]
59
64
----
60
65
import io.jooby.Jooby;
61
-
import io.jooby.jackson.JacksonModule;
66
+
import io.jooby.jackson.Jackson3Module;
62
67
63
-
public class App extends Jooby {
64
-
{
65
-
install(new JacksonModule()); // <1>
68
+
{
69
+
install(new Jackson3Module()); // <1>
66
70
67
-
jsonrpc(new MovieServiceRpc_()); // <2>
71
+
install(new JsonRpcJackson3Module()); // <2>
68
72
69
-
// Alternatively, you can override the default path:
The JSON-RPC extension delegates payload parsing and serialization to Jooby's standard JSON modules while enforcing strict JSON-RPC 2.0 compliance (such as the mutual exclusivity of `result` and `error` fields).
No additional configuration is required. The generated dispatcher automatically hooks into the installed engine using the `JsonRpcParser` and `JsonRpcDecoder` interfaces, ensuring primitive types are strictly validated and parsed.
106
107
107
-
===== Error Mapping
108
+
=== Error Mapping
108
109
109
110
Jooby seamlessly bridges standard Java application exceptions and HTTP status codes into the JSON-RPC 2.0 format using the `JsonRpcErrorCode` mapping. You do not need to throw custom protocol exceptions for standard failures.
110
111
@@ -123,7 +124,7 @@ When an application exception is thrown (like a `NotFoundException` with an HTTP
123
124
}
124
125
----
125
126
126
-
====== Standard Protocol Errors
127
+
==== Standard Protocol Errors
127
128
128
129
The engine handles core JSON-RPC 2.0 protocol errors automatically, returning HTTP 200 OK with the corresponding error payload:
Application-defined errors map standard HTTP status codes to the `-32000` to `-32099` range (e.g., an HTTP 404 maps to `-32004`, an HTTP 401 maps to `-32001`).
137
138
138
-
===== Batch Processing
139
+
=== Batch Processing
139
140
140
141
Batch processing is natively supported. Clients can send an array of JSON-RPC request objects, and the dispatcher will process them and return an array of corresponding response objects.
* link:{uiVersion}/modules/gRPC[gRPC]: A high-performance, strictly-typed protocol utilizing Protocol Buffers and HTTP/2 multiplexing. Ideal for backend-to-backend communication and polyglot microservices.
67
+
* link:{uiVersion}/modules/json-rpc[json-rpc]: A lightweight, stateless, and simple JSON-encoded protocol. Excellent for rapid integrations and environments where standard JSON is preferred.
68
+
* link:{uiVersion}/modules/tRPC[tRPC]: A RPC implementation that provides end-to-end type safety directly between your Java backend and TypeScript clients, without requiring intermediate build steps or code generation.
Copy file name to clipboardExpand all lines: docs/asciidoc/modules/tRPC.adoc
+15-19Lines changed: 15 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,11 +4,13 @@ The tRPC module provides end-to-end type safety by integrating the https://trpc.
4
4
5
5
Because tRPC is provided in its own module, you will need to add the `jooby-trpc-*` dependencies to your project. This integration allows you to write standard Java/Kotlin controllers and consume them directly in the browser using the official `@trpc/client`—complete with 100% type safety, autocomplete, and zero manual client generation.
6
6
7
-
[dependency, artifactId="jooby-jackson3:Jackson Module, jooby-trpc-jackson3:Trpc Jackson Module, jooby-trpc:Trpc Module"]
Installing tRPC in your Jooby app is a 3-step process. Because tRPC relies heavily on JSON serialization to communicate with the frontend client, you must install a JSON module, followed by its corresponding tRPC bridge module, and finally the core `TrpcModule`.
0 commit comments