server/module: vertx support #3778

- documentation
- bug fixing and API improvements

Author: jknack

docs/asciidoc/index.adoc

@@ -62,8 +62,8 @@ Latest Release: https://github.com/jooby-project/jooby/releases/tag/v{joobyVersi
 
 Looking for a previous version?
 
-* Access to link:v3[3.x] documentation. See link:/migration/4.x[migrating from 3.x to 4.x]
-* Access to link:v2[2.x] documentation. See link:/migration/3.x[migrating from 2.x to 3.x]
+* Access to link:v3[3.x] documentation. link:/migration/4.x[Migrating from 3.x to 4.x]
+* Access to link:v2[2.x] documentation. link:/migration/3.x[Migrating from 2.x to 3.x]
 * Access to link:v1[1.x] documentation.
 ====
 
@@ -76,7 +76,7 @@ Looking for a previous version?
 * link:modules/openapi[OpenAPI 3] support
 * <<execution-model, Event Loop and blocking execution modes>>
 * <<responses, Reactive responses>> (Completable Futures, RxJava, Reactor, SmallRye types and Kotlin Coroutines)
-* <<server, Multi-server>> including https://www.eclipse.org/jetty[Jetty], https://netty.io[Netty] and http://undertow.io[Undertow]
+* <<server, Multi-server>> including https://www.eclipse.org/jetty[Jetty], https://netty.io[Netty], https://vertx.io[Vertx] and http://undertow.io[Undertow]
 * Make the jump to full-stack framework with the extension/plugin mechanism and a variety of link:modules[]
 
 === Script API

docs/asciidoc/modules/modules.adoc

@@ -26,6 +26,8 @@ Available modules are listed next.
    * link:/modules/jdbi[Jdbi]: Jdbi module.
    * link:/modules/kafka[Kafka]: Kafka module.
    * link:/modules/redis[Redis]: Redis module.
+   * link:/modules/vertx-mysql-client[Vertx mySQL client]: Vertx reactive mySQL client module.
+   * link:/modules/vertx-pg-client[Vertx Postgres client]: Vertx reactive Postgres client module.
 
 === Validation
    * link:/modules/avaje-validator[Avaje Validator]: Avaje Validator module.

docs/asciidoc/modules/vertx-mysql-client.adoc

@@ -0,0 +1,9 @@
+== Sql Client
+
+A https://github.com/eclipse-vertx/vertx-sql-client[reactive SQL Client]. Supported databases:
+
+- MySQL
+
+These modules require a Vertx instance available in the service registry.
+
+include::vertx-sql-client.template[artifactId="jooby-vertx-mysql-client" sqlClient="MySQL" moduleName="VertxMySQLModule" builderName="MySQLBuilder"]

docs/asciidoc/modules/vertx-pg-client.adoc

@@ -0,0 +1,9 @@
+== Sql Client
+
+A https://github.com/eclipse-vertx/vertx-sql-client[reactive SQL Client]. Supported databases:
+
+- PostgreSQL
+
+These modules require a Vertx instance available in the service registry.
+
+include::vertx-sql-client.template[artifactId="jooby-vertx-pg-client" sqlClient="Postgres" moduleName="VertxPgModule" builderName="PgBuilder"]

docs/asciidoc/modules/vertx-sql-client.adoc

@@ -7,65 +7,6 @@ A https://github.com/eclipse-vertx/vertx-sql-client[reactive SQL Client]. Suppor
 
 These modules require a Vertx instance available in the service registry.
 
-=== MySQL client
-
-1) Add the dependency:
-
-[dependency, artifactId="jooby-vertx-mysql-client"]
-.
-
-2) Install
-
-.Java
-[source, java, role="primary"]
-----
-import io.jooby.vertx.VertxModule;
-import io.jooby.vertx.VertxMySQLModule;
-import static io.jooby.vertx.VertxHandler.vertx;
-
-{
-  install(new VertxModule());                                                  <1>
-
-  use(vertx());                                                                <2>
-
-  get("/{id}", ctx -> {
-    var db = require(SqlClient.class);                                         <3>
-    return db.preparedQuery("SELECT id, randomnumber from WORLD where id=$1")  <4>
-        .execute(Tuple.of(ctx.path("id").longValue()))
-        .map(result -> {
-          var row = result.iterator().next();
-          return new World(row.getInteger(0), row.getInteger(1));
-        });
-  });
-}
-----
-
-.Kotlin
-[source, kt, role="secondary"]
----- 
-import io.jooby.vertx.VertxModule
-import io.jooby.vertx.VertxMySQLModule
-import static io.jooby.vertx.VertxHandler.vertx
-
-{
-  install(VertxModule())                                                       <1>
-
-  use(vertx())                                                                 <2>
-
-  get("/{id}") {
-    val db = require(SqlClient::class)                                         <3>
-    db.preparedQuery("SELECT id, randomnumber from WORLD where id=$1")         <4>
-        .execute(Tuple.of(ctx.path("id").longValue()))
-        .map({ result ->
-          val row = result.iterator().next()
-          World(row.getInteger(0), row.getInteger(1))
-        })
-  }
-}
-----
-
-<1> Install Vertx
-<2> Install vertx handler. Render future, promise and buffer.
-<3> Get SQL client instance
-<4> Run a database query
+include::vertx-sql-client.template[artifactId="jooby-vertx-mysql-client" sqlClient="mysql" moduleName="VertxMySQLModule" builderName="MySQLBuilder" port=3306]
 
+include::vertx-sql-client.template[artifactId="jooby-vertx-pg-client" sqlClient="postgresql" moduleName="VertxPgModule" builderName="PgBuilder" port=5432]

docs/asciidoc/modules/vertx.adoc

@@ -2,6 +2,12 @@
 
 https://vertx.io/[Vertx] Reactive applications on the JVM.
 
+This module export the following services:
+
+- io.vertx.core.Vertx
+- io.vertx.core.eventbus.EventBus
+- io.vertx.core.file.FileSystem
+
 === Usage
 
 1) Add the dependency:
@@ -120,4 +126,132 @@ import io.jooby.vertx.VertxModule;
 }
 ----
 
-include::vertx-sql-client.adoc[]
+include::modules/vertx-sql-client.adoc[]
+
+== Vertx Server (Advanced)
+
+The javadoc:vertx.VertxServer[] allow you to share the Vertx acceptor and event loop groups within 
+the javadoc:netty.NettyServer[], so both vertx and netty web server implementation share the same
+resources. See https://vertx.io/docs/guides/advanced-vertx-guide/#integrating-netty[for more information].
+
+The vertx server must be manually provided at boot time (there is no service loader support for it):
+
+.Java
+[source, java, role="primary"]
+----
+import io.jooby.vertx.VertxServer;
+
+{
+  get("/vertx", ctx -> {
+    return "Running from vertx event loop";
+  });
+}
+
+public static void main(String[] args) {
+  runApp(args, new VertxServer(), EVENT_LOOP, App::new);
+}
+----
+
+.Kotlin
+[source, kt, role="secondary"]
+---- 
+import io.jooby.vertx.VertxServer
+
+import io.jooby.vertx.VertxServer;
+
+{
+  get("/vertx") {
+    "Running from vertx event loop"
+  }
+}
+
+un main(args: Array<String>) {
+  runApp(args, VertxServer(), EVENT_LOOP, ::App)
+}
+----
+
+If you run multiple applications, they all share a single Vertx instance.
+
+[IMPORTANT]
+====
+*VertxModule must NOT be installed while running on VertxServer*
+====
+
+One of the main benefits of running on the VertxServer is to share/reuse the event loop threads.
+You can run non-blocking code on the Vertx event loop thread without context switch. A good example
+of this is to run within
+
+=== Sql Connection
+
+These modules exist as part of the performance tests required by https://www.techempower.com/benchmarks[Techempower].
+
+You are free to use them, but keep in mind they are for very specific kind of application.
+
+include::vertx-sql-connection.template[artifactId="jooby-vertx-mysql-client" sqlClient="MySQL" moduleName="VertxMySQLConnectionModule"]
+
+include::vertx-sql-connection.template[artifactId="jooby-vertx-pg-client" sqlClient="Postgres" moduleName="VertxPgConnectionModule"]
+
+
+==== How it works?
+
+There is an internal Verticle (one per IO threads) with a dedicated https://vertx.io/docs/apidocs/io/vertx/sqlclient/SqlConnection.html[SqlConnection]. This connection is only 
+accessible from a Vertx thread any attempt to access to the connection from a non Vertx thread
+will result in exception.
+
+Same applies for the https://vertx.io/docs/apidocs/io/vertx/sqlclient/PreparedStatement.html[PreparedStatement] / https://vertx.io/docs/apidocs/io/vertx/sqlclient/PreparedQuery.html[PreparedQuery] instances.
+
+.PreparedStatement example:
+[source,java]
+----
+import io.jooby.Reified;
+
+String SELECT_WORLD = "SELECT id, randomnumber from WORLD where id=$1";
+
+Reified<PreparedQuery<RowSet<Row>>> PreparedQueryType =
+    getParameterized(PreparedQuery.class, getParameterized(RowSet.class, Row.class));
+
+{
+  install(new VertxPgConnectionModule()
+     .preparedStatement(Map.of("selectWorld", List.of(SELECT_WORLD)))      <1>
+  );
+
+  use(vertx());                                                            <2>
+
+  var selectWorldQuery = ctx.require(PreparedQueryType, "selectWorld");    <3>
+  get("/world/{id}", ctx -> {
+    return selectWorldQuery.execute(Tuple.of(ctx.path("id").longValue()))
+          .map(
+              result -> {
+                var row = result.iterator().next();
+                return new World(row.getInteger(0), row.getInteger(1));
+              });
+  });
+}
+
+public static void main(String[] args) {
+  runApp(args, new VertxServer(), EVENT_LOOP, App::new);
+}
+----
+
+<1> Created a prepared statement. This is done when Verticle is deployed
+<2> Add Vertx handler, so it can render Future and Promise.
+<3> Get a reference to the prepared statement
+
+The line:
+
+    var selectWorldQuery = ctx.require(PreparedQueryType, "selectWorld");
+
+Allow you to get a reference/proxy to the prepared statement/query. The proxy will thrown an exception
+if you try to use from a non Vertx thread. The prepared statement is compiled when the Verticle
+is deployed (at application startup time).
+
+If you work with any of the dependency injection supported framework, you can inject the prepared
+statement like:
+
+[source,java]
+----
+@Inject
+public WorldRepository(@Named("selectWorld") PreparedQuery<RowSet<Row>> selectWorld) {
+  this.selectWorld = selectWorld;
+}
+----

docs/asciidoc/servers.adoc

@@ -4,6 +4,7 @@ There are three server implementations:
 
 - javadoc:jetty.JettyServer[artifact=jooby-jetty]
 - javadoc:netty.NettyServer[artifact=jooby-netty]
+- javadoc:vertx.VertxServer[artifact=jooby-vertx]
 - javadoc:undertow.UndertowServer[artifact=jooby-undertow]
 
 Servers are automatically registered based on their presence on the project classpath.
@@ -23,6 +24,14 @@ To use Undertow, add the dependency:
 [dependency, artifactId="jooby-undertow"]
 .
 
+To use Vertx, add the dependency:
+
+[dependency, artifactId="jooby-vertx"]
+
+.
+
+The javadoc:vertx.VertxServer[] setup is fully described link:/modules/vertx#vertx-server-advanced[here].
+
 [IMPORTANT]
 ====
 Only one server dependency must be available on classpath.
@@ -62,7 +71,7 @@ first setup wins.
 
 === Manual setup
 
-Servers are automatically loaded using `ServiceLoader` API. If you need to add it manually:
+Servers are automatically loaded using `ServiceLoader` API:
 
 .Server
 [source,java,role="primary"]

docs/asciidoc/templates/vertx-sql-client.adoc

@@ -0,0 +1,97 @@
+=== {{sqlClient}}
+
+1) Add the dependency:
+
+[dependency, artifactId="{{artifactId}}"]
+.
+
+2) Define connection string or key/value pairs details:
+
+.application.conf
+[source, properties]
+----
+db = {{sqlClient}}//dbuser:secretpassword@localhost:{{port}}/mydb
+----
+
+.application.conf
+[source, properties]
+----
+db.host = localhost
+db.port = {{port}}
+db.database = mydb
+db.user = dbuser
+db.password = secretpassword
+----
+
+3) Install
+
+.Java
+[source, java, role="primary"]
+----
+import io.jooby.vertx.VertxModule;
+import io.jooby.vertx.{{moduleName}};
+import static io.jooby.vertx.VertxHandler.vertx;
+
+{
+  install(new VertxModule());                                          <1>
+  
+  install(new {{moduleName}}());                                     <2>
+  
+  use(vertx());                                                        <3>
+
+  get("/{id}", ctx -> {
+    var db = require(SqlClient.class);                                 <4>
+    return db.preparedQuery("SELECT id, name from World where id=$1")  <5>
+        .execute(Tuple.of(ctx.path("id").longValue()))
+        .map(result -> {
+          var row = result.iterator().next();
+          return new World(row.getInteger(0), row.getInteger(1));
+        });
+  });
+}
+----
+
+.Kotlin
+[source, kt, role="secondary"]
+---- 
+import io.jooby.vertx.VertxModule
+import io.jooby.vertx.{{moduleName}}
+import static io.jooby.vertx.VertxHandler.vertx
+
+{
+  install(VertxModule())                                               <1>
+
+  install({{moduleName}}());                                           <2>
+
+  use(vertx())                                                         <3>
+
+  get("/{id}") {
+    val db = require(SqlClient::class)                                 <4>
+    db.preparedQuery("SELECT id, name from World where id=$1")         <5>
+        .execute(Tuple.of(ctx.path("id").longValue()))
+        .map({ result ->
+          val row = result.iterator().next()
+          World(row.getInteger(0), row.getInteger(1))
+        })
+  }
+}
+----
+
+<1> Install Vertx
+<2> Install Sql Client: {{sqlClient}
+<3> Install vertx handler. Render future, promise and buffer
+<4> Get SQL client instance
+<5> Run a database query
+
+To use the client version of the driver:
+
+.Client
+[source, java]
+----
+
+{
+  ...
+  install(new {{moduleName}}({{builderName}}::client));
+  ...
+}
+----