GuicedEE Web Skill | Agent Skills

GuicedEE Web

Reactive HTTP/HTTPS server bootstrap for GuicedEE applications using Vert.x 5.

Core Concept

Provides the Router, HttpServer, and BodyHandler plumbing that higher-level modules (rest, websockets, etc.) build on top of. Configuration is environment-driven; extension is SPI-driven. The server starts automatically via IGuicePostStartup.

Required Flow

Add com.guicedee:web dependency.

Bootstrap GuicedEE — the web server starts automatically:

IGuiceContext.registerModuleForScanning.add("my.app");
IGuiceContext.instance().inject();
// HTTP server is now listening on port 8080 (default)

Add routes by implementing VertxRouterConfigurator:

public class MyRoutes implements VertxRouterConfigurator<MyRoutes> {
    @Override
    public Router builder(Router router) {
        router.get("/health").handler(ctx -> ctx.response().end("OK"));
        return router;
    }

    @Override
    public Integer sortOrder() { return 500; }
}

module my.app {
    requires com.guicedee.vertx.web;
    provides com.guicedee.vertx.web.spi.VertxRouterConfigurator
        with my.app.MyRoutes;
}

SPI Extension Points

All SPIs are discovered via ServiceLoader. Register with JPMS provides...with or META-INF/services.

| SPI | When it runs | Purpose | |---|---|---| | VertxHttpServerOptionsConfigurator | Before servers created | Customize HttpServerOptions (ports, TLS, compression) | | VertxHttpServerConfigurator | After server creation | Configure HttpServer instance (WebSocket upgrade, connection hooks) | | VertxRouterConfigurator | After body handler | Add routes, middleware, handlers to the Router |

Configuration

All configuration is driven by system properties or environment variables:

| Variable | Default | Purpose | |---|---|---| | HTTP_ENABLED | true | Enable HTTP server | | HTTP_PORT | 8080 | HTTP listen port | | HTTPS_ENABLED | false | Enable HTTPS server | | HTTPS_PORT | 443 | HTTPS listen port | | HTTPS_KEYSTORE | — | Path to JKS or PKCS#12 keystore | | HTTPS_KEYSTORE_PASSWORD | — | Keystore password | | VERTX_MAX_BODY_SIZE | 524288000 (500 MB) | Maximum request body size |

TLS/HTTPS

Keystore format is auto-detected by file extension:

.jks → JKS
.pfx, .p12, .p8 → PKCS#12

Startup Flow

IGuiceContext.instance().inject()
 └─ IGuicePostStartup hooks
     └─ VertxWebServerPostStartup (sortOrder = MIN_VALUE + 500)
         ├─ Build HttpServerOptions (compression, keepalive, header limits)
         ├─ Apply VertxHttpServerOptionsConfigurator SPIs
         ├─ Create HTTP / HTTPS servers
         ├─ Apply VertxHttpServerConfigurator SPIs
         ├─ Create Router + BodyHandler
         ├─ Apply VertxRouterConfigurator SPIs (sorted)
         ├─ Mount per-verticle sub-routers
         ├─ Configure Jackson ObjectMapper via IJsonRepresentation
         └─ server.listen()

Non-Negotiable Constraints

Never create HttpServer manually — use the auto-started server from VertxWebServerPostStartup.
Module must requires com.guicedee.vertx.web;.
SPI implementations must be dual-registered (module-info.java + META-INF/services/).
VertxRouterConfigurator implementations control ordering via sortOrder().

Agent Skills: GuicedEE Web

Install this agent skill to your local

Skill Files