druvu-lib-web

A lightweight Java web framework built on Jetty. Define handlers, add auth — your app is running in under 20 lines.

View on GitHub

---

Overview

druvu-lib-web is a modular web framework for Java that gets out of your way. It runs on Jetty 12 and gives you HTTP handlers, WebSocket support, authentication, and a PHP-like template engine — all wired together with convention over configuration. Handler classes map to URL paths automatically, templates are resolved by name, and plugins are discovered via ServiceLoader.

---

Quick Example

WebBoot boot = new WebBoot(WebConfig.builder()
    .port(8080)
    .urlConfig(UrlConfig.from(DashboardHandler.class))
    .urlConfig(UrlConfig.from(UsersHandler.class, "admin:access"))
    .authConfig(AuthConfig.builder()
        .basicAuth()
        .user("admin", "secret", "admin:access")
        .build())
    .build());

boot.start("/myapp");
// Server running at http://localhost:8080/myapp/

public class DashboardHandler implements HttpHandler {
    @Override
    public void handle(HttpRequest request, HttpResponse response) {
        // handler logic runs, then forwards to dashboard.php template
    }
}

<!-- dashboard.php -->
<?php require 'includes/header.php'; ?>
<h1>Welcome, <?= context() ?></h1>
<a href="<?= link('users') ?>">Manage Users</a>
<?php require 'includes/footer.php'; ?>

---

Features

Feature	Description
Convention Routing	DashboardHandler maps to /dashboard automatically — no annotations, no XML
Built-in Auth	Basic auth with inline users or custom UserStore for databases/LDAP
Per-URL Permissions	Attach permission strings when registering handlers
WebSocket Support	JSON-based real-time messaging with session management
PHP Template Engine	Java-based PHP-like templates — includes, expressions, and helper functions
WebJars Integration	Reference CSS/JS libraries with webjar('bootstrap.min.css') — no version hardcoding
Plugin Architecture	Template engines discovered via ServiceLoader; drop a jar, it’s picked up
JSON APIs	Call response.commitContent() to return JSON — skips template rendering

---

Module Architecture

druvu-lib-web-parent/
  druvu-lib-web-api        Pure interfaces & contracts (no runtime dependencies)
  druvu-lib-web-core       Jetty 12 server, dispatcher, auth, WebSocket engine
  druvu-lib-web-php        PHP template engine plugin (auto-discovered via ServiceLoader)
  druvu-lib-web-example    Demo app with dashboard, grid, JSON API, and WebSocket chat

The API module defines all contracts. The core module provides the Jetty-based implementation. Template engines are plugins — drop a jar on the classpath and it’s picked up automatically.

---

Handler Routing

Handler class names map to URL paths by convention:

Class Name	URL Path
DashboardHandler	/dashboard
UserProfileHandler	/user-profile
API	/api

The Handler suffix is stripped, CamelCase is converted to kebab-case. If a handler does not commit the response, the framework forwards to the matching template (e.g. dashboard.php).

---

Authentication

AuthConfig.builder()
    .basicAuth()
    .realm("My Application")
    .sessionTimeout(3600)
    .user("admin", "secret", "admin:all", "user:read")
    .user("viewer", "pass", "user:read")
    .build()

For production, implement the UserStore interface to load users from a database, LDAP, or any external source. Permissions are checked before handler invocation — unauthorized requests get a 401.

---

Tech Stack

Component	Technology
Server	Jetty 12 (EE10 Servlet API)
Language	Java 25
Build	Maven
Template Engine	PHP-like (Java-based, pluggable)
WebSocket	Jetty WebSocket API, JSON via GSON
Asset Management	WebJars + WebJarAssetLocator
Plugin Discovery	ServiceLoader (via druvu-lib-loader)
Testing	TestNG

---

Requirements

• Java 25+
• Maven 3.9+

---

License

Apache License 2.0

---

Links

• GitHub Repository